lxy.exp.mov: Create an animation from a LoCoH-xy object
In tlocoh: Constructs homeranges and explores time use patterns from location data

Create an animation from a LoCoH-xy object

lxy.exp.mov(lxy, id = NULL, all.ids.at.once = TRUE,
  all.ids.col.unique = all.ids.at.once, all.ids.col = NULL,
  all.ids.legend = c("bottomright", "bottom", "bottomleft", "left",
  "topleft", "top", "topright", "right", "center")[5],
  all.ids.legend.cex = 0.8, dt.start = NULL, dt.end = NULL,
  frame.method = c("auto", "time", "location")[1], frame.rtd = "auto",
  xlim = NULL, ylim = NULL, dt.label = TRUE, dt.label.x = NULL,
  dt.label.y = NULL, dt.label.col = "black", dt.label.bg = "gray90",
  title = NULL, title.show = TRUE, axes.show = TRUE,
  axes.ticks = axes.show, axes.titles = FALSE, mar.map = c(0.7 + (if
  (axes.ticks) 0.9 else 0) + (if (axes.titles) 1.3 else 0), 0.5 + (if
  (axes.ticks) 0.9 else 0) + (if (axes.titles) 1.3 else 0), if (title.show)
  2.1 else 0.5, 0.5), mgp.map = c(0.4 + if (axes.ticks) 1.2 else 0, 0.4,
  0), col.xys.active = "red", col.xys.background = "gray80",
  cex.xys.active = 1.5, cex.xys.background = 0.5, tz.local = NULL,
  tz.local.check = TRUE, col.by.hour.of.day = FALSE,
  col.hod = colorRampPalette(colors()[c(24, 30, 553, 121, 26, 121, 553,
  30, 24)])(24), width = if (screen.test) 7 else 608, height = NULL,
  max.frames = NULL, png.pointsize = 16 + (width - 480)/80,
  screen.test = FALSE, tmp.dir = NULL, tmp.files.delete = TRUE,
  prompt.continue = TRUE, fn.mov = NULL, fn.mov.dir = getwd(),
  fn.mov.exists = c("auto.increment", "overwrite", "stop", "ask")[1],
  duration = NULL, fps = NULL, skip = NULL, ffmpeg = NULL,
  create.mov = TRUE, show.cmd = FALSE, fmt = c("mov", "mp4")[1],
  info.only = TRUE, shp.csv = NULL, layers = NULL, tiff.fn = NULL,
  tiff.bands = c(3, 2, 1), tiff.col = gray(0:255/255),
  tiff.pct = FALSE, tiff.buff = 0, tiff.fill.plot = TRUE,
  bg2png = !is.null(layers), crop.layers.to.extent = TRUE,
  date.bar = 0.85, date.bar.bins = 12, col.db = "darkblue",
  cex.axis.db = 0.7, beep = FALSE, report.time = TRUE,
  status = TRUE)

`lxy`	A LoCoH-xy object
`id`	The id value(s) to be on the plot
`all.ids.at.once`	Display all the individual ids simultaneously. If False, an animation will be created for each id. T/F.
`all.ids.col.unique`	Whether to use unique colors for each individual when plotting multiple individuals simultaneously, T/F
`all.ids.col`	A named list of color values; the element names must match the name(s) of the ids
`all.ids.legend`	Where to place a legend showing the color of each id (for an animation showing the movement of multiple individuals simultaneously): 'bottomright', 'bottom', 'bottomleft', 'left', 'topleft', 'top', 'topright', 'right', or 'center'. May also be `NULL`, in which case the legend will not be displayed. Ignored if `ids.legend.bln=FALSE` or `all.ids.col.unique = FALSE`.
`all.ids.legend.cex`	The character expansion factor for the id legend. See parameter `all.ids.legend` above.
`dt.start`	The starting date-time. An object of class POSIXt or one that can be coerced to POSIXt. If NULL, the earliest date-time in the series will be used.
`dt.end`	The ending date-time. An object of class POSIXt or one that can be coerced to POSIXt. If NULL, the last date-time in the series will be used.
`frame.method`	How each frame should be defined temporally, "time" - each frame represents a fixed amount of time, "location" each frame is a point in the series
`frame.rtd`	The real-time duration of each frame (in seconds). If "auto" (default), the lowest median sampling frequency will be used
`xlim`	A two-element numeric vector for the range of the x-axis (in map units)
`ylim`	A two-element numeric vector for the range of the y-axis (in map units)
`dt.label`	Add a label for the date of the frame
`dt.label.x`	The x-coordinate for the date label (ignored if `dt.label=FALSE`)
`dt.label.y`	The y-coordinate for the date label (ignored if `dt.label=FALSE`)
`dt.label.col`	A color value/name for the date label (ignored if `dt.label=FALSE`)
`dt.label.bg`	The background color for the date label. Set to `NA` for a transparent background. (ignored if `dt.label=FALSE`)
`title`	A title for the map
`title.show`	Whether to show the title. T/F.
`axes.show`	Whether to show the axes (ticks, labels and titles). Can be over-written by `axes.ticks` and `axes.titles`. T/F.
`axes.ticks`	Whether to show the tick marks and labels on the axes. T/F.
`axes.titles`	Whether to show axes titles. T/F.
`mar.map`	Margin settings for the map, see `par`
`mgp.map`	Locations of the axes elements for the map, see `par`
`col.xys.active`	Color of the active point. Ignored if `col.by.hour.of.day = TRUE`.
`col.xys.background`	Color of the non-active points. To hide non-active points, set this to `NA`.
`cex.xys.active`	The character expansion factor of the active point
`cex.xys.background`	The character expansion factor of non-active points
`tz.local`	The name of the time zone of the study area
`tz.local.check`	Check whether tz.local is a valid timezone name (not implemented) T/F.
`col.by.hour.of.day`	Whether to color the active point by the hour of day (i.e., dark colors at night, orange for day time locations). T/F
`col.hod`	A vector of 24 color values used to symbolize the color of the active point by the hour of day. Ignored if `col.by.hour.of.day = FALSE`.
`width`	The width of each frame in pixels (if `screen.test=FALSE`) or inches (if `screen.test=TRUE`).
`height`	The height of each frame in pixels (if `screen.test=FALSE`) or inches (if `screen.test=TRUE`).
`max.frames`	The maximum number of frames to produce.
`png.pointsize`	The pointsize (in pixels) for the PNG image, equivalent to the height or width of a character in pixels (increase to make labels appear larger)
`screen.test`	Create up to three sample frame(s) on the screen (instead of PNG files)
`tmp.dir`	A directory where temporary PNG files for each frame will be created, character.
`tmp.files.delete`	Delete the temporary PNG files when done, T/F
`prompt.continue`	Whether to present a summary of the encoding settings and get user confirmation before continuing, T/F
`fn.mov`	The path and filename of output file (either .mov or .mp4). If NULL a filename will be automatically generated
`fn.mov.dir`	The directory where the animation will be saved (ignored if a value for `fn.mov` is passed)
`fn.mov.exists`	What to do if the animation file already exists: "auto.increment", "overwrite", "stop", or "ask".
`duration`	The desired duration of the animation (in seconds)
`fps`	A numeric value for frames per second
`skip`	Output every nth frame. To include every frame set skip=1. Integer.
`ffmpeg`	The name of the ffmpeg executable. If NULL (the default), a default file name will be used. See notes.
`create.mov`	Whether to actually create the mov file. Set to FALSE preview a few frames without actually encoding them.
`show.cmd`	Whether to display the ffmpeg command line that stitches the images into an animation
`fmt`	Video format: `'mov'` (Quicktime animation codec) or `'mp4'` (h.264)
`info.only`	Only return info
`shp.csv`	The path and filename of a csv file that contains information about shapefiles, including layer names, file, and symbology.
`layers`	The name(s) of layers in shp.csv to display in the background. Will be displayed using the symbology in shp.csv. Character vector or comma delimited string.
`tiff.fn`	The path and name of a GeoTIFF file (e.g., satellite image) that will be displayed in the background. See notes.
`tiff.bands`	A vector of threee integers corresponding to the bands of the GeoTIFF image that will be mapped to the red, green and blue color guns respectively.
`tiff.col`	A vector of color values for plotting single-band images in the background. Ignored if using three bands.
`tiff.pct`	Whether or to convert the GeoTIFF to an indexed 256 color RGB image, which may speed up drawing. T/F.
`tiff.buff`	A numeric buffer distance in map units that the range of the plot will be expanded so the points are not right on the edge of the GeoTIFF.
`tiff.fill.plot`	Whether to fill the entire plot area with the GeoTIFF. T/F.
`bg2png`	Save the plot background elements as a static raster image (to improve speed), ignored if `screen.test=TRUE`
`crop.layers.to.extent`	Whether to crop the shapefile layers to the view extent (may speed up drawing time)
`date.bar`	The height of the lower section of the plot to devote to the time bar, in inches. To hide the time bar completely, set `date.bar=0`.
`date.bar.bins`	The target number of bins (tick marks + 1) on the time bar (integer)
`col.db`	A single color value for the date bar axes / tick labels, character
`cex.axis.db`	Character expansion factor for the labels on the date bar axis.
`beep`	Beep when done, T/F
`report.time`	Show the time taken when done, T/F
`status`	Show progress bar and status messages

A list with information about each file created. Each element of the list is another list with two elements: fn (the full filename) and dim (a two-element numeric vector with the frame width and height). If no animation file(s) were created, returns NULL.

This function creates an animation from a LoCoH-xy object. There are three general steps in the workflow: 1) design the frame layout, 2) choose values for the speed and duration of the animation, and 3) create the animation.

One will normally want to run the function a few times without actually encoding to tweak the frame design (e.g., where the date label and legend appear). To see what a frame in the output will approximately look like, set screen.test=TRUE. See Appendix VI of the T-LoCoH tutorial for further details.

If you have locations for all hours of the day, you can color the active point by the hour-of-day by setting col.by.hour.of.day=TRUE. This can help you visualize daily patterns in movement, assuming that the time-stamps of each point are in local time. Locations at night will appear dark, sunrise and sunset reddish, and mid-day points blue (these colors can be adjusted by passing a different value for col.hod.

To create the animation, two and only two of the following parameters must be passed: duration, fps, and skip. The third parameter will be computed based on the other two. To include every frame, pass fps, set skip=1, and leave duration out.

Larger values for fps will result in the animation running 'faster'. Values between 10 and 20 often work well; beyond 30 fps the eye can't keep up with the motion Note if you pass values for fps and duration, an appropriate value for skip will be computed but the final duration of the animation may not be exactly equal to duration because only interger values of skip are allowed.

tmp.dir="." (or another folder), create.mov=FALSE, and tmp.files.delete=FALSE. This will generate a few sample frames as PNG files but not delete them so you can inspect them using an image viewer. Once these look good, create the full animation by setting create.mov=TRUE and max.frames=NULL.

If frame.method is 'auto', the script will use time-based frames when multiple individuals are being animated simultaneously, and location-based frames otherwise.

duration (the duration of the animation in seconds) should not be confused with frame.rtd which is the real-time duration of a single frame in seconds (e.g., frame.rtd=3600 means each frame will represent 1 hour).

If date.bar is too small or too large, you might get a 'margins too large' error. Try values around 1, or hide the date bar completely by setting date.bar=0.

The output animation is encoded in QuickTime format or mp4. The Quicktime file is encoded using Quicktime's 'animation' codec, a lossless format that 'scrubs' well (i.e., you can drag the scroll bar to view frame by frame). The mp4 settings use the h.264 compression algorithm with a constant rate factor of 20 (good quality). In both cases, encoding requires installing the open source encoding program ffmpeg. ffmpeg is a command line program that can be downloaded from http://ffmpeg.org/download.html (select the package for your OS). After downloading, the ffmpeg executable file should be saved in the current working directory, or a directory on the PATH environment variable (e.g., on windows c:\windows). You may also pass the path and name to ffmpeg using the ffmpeg argument.

If ffmpeg is not available, you can still use this function to generate the individual frames and then use another utility (e.g., ImageMagick, Quicktime Pro) to combine the frames into a video file. For best results use a 'lossless' compression method in the encoding program. To create the individual frames only for encoding with another utility, set tmp.dir="." (the working directory) and tmp.files.delete=FALSE. Passing show.cmd=TRUE will display the ffmpeg command line that will generate animation, which can be useful if you want to do some additional editing to the frames prior to encoding.

If fn.mov.exists = "auto.increment", a two-digit number will be appended to the filename to avoid overwriting an existing file

tlocoh documentation built on May 2, 2019, 5:27 p.m.