lhs.exp.mov: Create a Quicktime animation from a LoCoH-hullset object
In tlocoh: Constructs homeranges and explores time use patterns from location data

Create a Quicktime animation from a LoCoH-hullset object

lhs.exp.mov(lhs, id = NULL, k = NULL, r = NULL, a = NULL,
  s = NULL, hs.names = 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",
  rtd.center = TRUE, clean.multihull.frames = 4, xlim = NULL,
  ylim = NULL, dt.label = TRUE, dt.label.col = "black",
  dt.label.col.bg = NA, dt.label.x = NULL, dt.label.y = NULL,
  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.hull.active = "red", col.hull.alpha = 255, 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 = "ffmpeg.exe",
  create.mov = TRUE, info.only = TRUE, shp.csv = NULL,
  layers = NULL, tiff.fn = NULL, tiff.pct = FALSE,
  tiff.bands = c(4, 3, 2), tiff.buff = 500, 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)

`lhs`	A `LoCoH-hullset` object
`id`	The id value(s) to be on the plot
`k`	The k value of hullsets to export
`r`	The r value of hullsets to export
`a`	The a value of hullsets to export
`s`	The s value of hullsets to export
`hs.names`	The name(s) of saved hullsets to export
`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
`rtd.center`	Whether to center the start and end time of the first frame around the time stamp of the first location, to help ensure that each frame has only one hull in it. T/F.
`clean.multihull.frames`	A numeric value that determines whether and how much a hull can be time shifted to avoid having two active hulls in the same frame. Pass `0` to disable cleaning multi-hull frames. See details.
`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.col`	A color value/name for the date label (ignored if `dt.label=FALSE`)
`dt.label.col.bg`	The background color for the date label (`NA` for transparent background, ignored if `dt.label=FALSE`)
`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`)
`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.hull.active`	The color of the active hull
`col.hull.alpha`	A number 0..255 for the alpha value for the hull color (semi-transparency); 0=completely transparent, 255=opaque
`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 Quicktime *.mov file. 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 file. See notes.
`create.mov`	Whether to actually create the mov file. Set to FALSE preview a few frames without actually encoding them.
`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.pct`	Whether or to convert the GeoTIFF to an indexed 256 color RGB image, which may speed up drawing. T/F.
`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.buff`	A numeric buffer distance 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 one, 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 *.mov 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 *.mov file(s) were created, returns NULL.

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

One will normally want to run the function a few times without actually encoding to tweak the frame layout (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. Once the screen sample looks good, next set max.frames=3, tmp.dir="." (or another folder), create.mov=FALSE, and tmp.files.delete=FALSE. This will generate a few sample frames in PNG files and not delete them so you can inspect them. Once these look good, create the full animation by setting create.mov=TRUE.

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

Passing a positive value for clean.multihull.frames (default value is 4) enables time-shifting hulls if needed to prevent two hulls appearing in one frame and no hulls in the previous or next frame (which produces jerky playback when animated). The maximum amount of time a hull can be shifted is calculated by frame.rtd / clean.multihull.frames. Thus for example if frame.rtd=7200 (two hours), and clean.multihull.frames=4, then if a frame has two hulls appearing in it and the parent point of one of those hulls lies within 30 minutes (2 hours / 4) of the beginning or end of the frame, and there is no hull in the adjacent frame, that hull will be moved to the earlier / later frame. To disable this effect, set clean.multihull.frames = 0.

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. The Quicktime file is encoded using the 'animation' codec, a lossless format that 'scrubs' well (i.e., you can drag the scroll bar to view frame by frame). This requires installing the open source encoding program ffmpeg. ffmpeg is a command line program that Linux and Windows users can download from http://ffmpeg.org/download.html. Windows users should save the ffmpeg.exe file to the working directory or a directory on the path environment variable (e.g., c:\windows). Mac users can download ffmpegX from http://ffmpegx.com/download.html but this has not been tested (pass name to ffmpeg).

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, set tmp.dir="." (the working directory) and tmp.files.delete=FALSE.

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

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