Movement Data Visualization

Tools to visualize movement data (e.g. from GPS tracking) and temporal changes of environmental data (e.g. from remote sensing) by creating video animations.


Introduction

This is an R package providing tools to visualize movement data by creating path animations from geo-location point data. The package is under ongoing development. The moveVis package is working hand in hand with the move package by using the move and moveStack class and the raster package. It is based on a ggplot2 plotting architecture and relys on the libraries ImageMagick, ffmpeg and libav. To be informed about updates, new features and the current version, visit news.movevis.org.

Installation

This is the official moveVis R package repository, including beta code versions before submitted to CRAN. For operational use of moveVis, please use the current stable CRAN version of moveVis.

To install stable version from CRAN, please execute:

install.packages('moveVis')

To install the development version from this GitHub repository, please execute:

devtools::install_github("16EAGLE/moveVis")

Getting started

You can use moveVis with any move or moveStack object. This guide shortly explains how to prepare your own geo-location point data for the animate_move() function by creating a move class object from a data.frame class object. As an example, the provided example data (data.frame) are used. Instead, you could use any similar prepared data of yours.

External libraries

moveVis requires at least one of the three external libraries 'ffmpeg', 'libav' and/or 'ImageMagick'. They support different types of output formats (gif, mov, mp4 etc.). If you have 'ImageMagick' and either 'ffmepg' or 'libav' installed, you can use all output formats supported by moveVis.

Run get_libraries() to find out, which libraries are installed on your system:

get_libraries()

Linux

On many Linux distributions, ImageMagick and FFmpeg are preinstalled or can be installed via the package manager. On Ubuntu, use sudo apt-get install imagemagick to install ImageMagick containing the convert tool and sudo apt-get install ffmpeg to install FFmpeg containing the equally called ffmpeg tool.

Windows

You can download and install both ImageMagick and FFmpeg from https://www.imagemagick.org/script/download.php as binary for Windows. Make sure that you select "Install FFmpeg" and "Install legacy utilities (e.g. convert)" during the installation process. get_libraries will recognize both libraries only, if their commands can be called from the command line. Make sure that you select the related option during the installation process.

maxOS/OS X

Visit https://www.macports.org/install.php and follow the instructions there to download and install MacPorts. Execute sudo port install ImageMagick to install the latest binary release of ImageMagick for Mac. Visit https://www.ffmpeg.org/download.html to download and install the latest binary release of FFmpeg for Mac.

Install moveVis

After the required libraries are once installed, restart your R session. First, load moveVis and the move package:

#Load packages
library(moveVis)
library(move)

and then run get_libraries() to check, if the installed tools are recognized by moveVis. If so, everything is set for starting to create your first moveVis animation. If the installed tools are not recognized automatically, you can provide the paths to the tools manually (see argument conv_dir in the manual of animate_move())

Data preperation

You will need to load the example data for this tutorial:

#Load data (data.frame) (or use your own as data.frame)
data("move_data")

As the provided example data, your data.frame needs to have at least three columns: two columns for your coordinates (here "lat", "lon") and one for the date/time stamp (here "dt"). The date/time stamps need to be converted to POSIXct as follows:

move_data$dt <- as.POSIXct(strptime(move_data$dt, "%Y-%m-%d %H:%M:%S", tz = "UTC"))

Your movement data need to be provided as move class objects to the animate_move() function. For each individual movement path you want to display simultaniously within a single animation, you will need one move class object. The move class objects per path are provided as a list. If your data.frame contains several individuals (e. g. differentiable by a "individuals" column, as the example data.frame does), then subset the data per individual and store the namings. If you just want to display a single path, you do not have to do this.

#Create new move class object list by individual
data_ani <- split(move(move_data$lon, move_data$lat, proj=CRS("+proj=longlat +ellps=WGS84"),
                       time = move_data$dt, animal=move_data$individual, data=move_data))

Additional input variables

get_libraries() returns the library commands that are needed by the animate functions. Just save them to a variable that you can later pass to the animate function so that it knows how to call the extern library commands. You can also call get_formats() to see all output formats, you can choose from.

#Get libraries 
conv_dir <- get_libraries()
 
#Find out, which output file formats can be used
get_formats()
 

Last, you need to specify the output directory path and you can specify some optional variables such as the animation title (for details on all the arguments of animate_move() , read the animate_move() help).

#Specify output directory
out_dir <- paste0(getwd(),"/test")
 
#Specify some optional appearance variables
img_title <- "Movement of the white stork population at Lake Constance, Germany"
img_sub <- paste0("including individuals ",indi_names)
img_caption <- "Projection: Geographical, WGS84; Sources: Movebank 2013; Google Maps"

Animate function call

Finally, you are now prepared to call animate_move(), which will have to work for a while depending on your input. Here, for demonstrational purposes, we use frames_nmax set to 50 to force the function to only produce 50 frames and then finish the animation, regardless how many input points you provided. Set log_level to 1 to be informed of anything the function is doing. Set out_format to "mov" to get a .mov video output file.

#Call animate_move()
animate_move(data_ani, out_dir, conv_dir = conv_dir, tail_elements = 10,
             paths_mode = "true_data", frames_nmax = 50,
             img_caption = img_caption, img_title = img_title,
             img_sub = img_sub, log_level = 1, out_format = "mov")

After the function is finished, check the output directory. Retry everything with different settings and modes, described in the function manuals. Further examples and explanations are provided within the function manuals.

Contact & bug reports

moveVis is being developed and maintained by Jakob Schwalb-Willmann. For bug reports, please use https://github.com/16eagle/movevis/issues to contact me. Feature requests and other contributions are also welcome.

What else are we doing?

The Department of Remote Sensing of the University of Würzburg has developed other R packages that might interest you:

For other news on the work at at the Department of Remote Sensing of the University of Würzburg, click here.

Acknowledgements

This initiative is part of the Opt4Environment project and was funded by the German Aerospace Center (DLR) on behalf of the Federal Ministry for Economic Affairs and Energy (BMWi) with the research grant 50 EE 1403.

News

moveVis 1.0.0

Future implementations (not yet implemented!)


**Next version:** * "keep tracks" setting to force paths to not disappear * segmentation coulouring * optional user-defined font sizes of all fonts (axis, annotations etc.), colours based on ggplot2 syntax * optional user-defined map elements position vectors
**Maybe next version:** * user-defined area of interest (AOI), which scales map extent to specific area without excluding tracks "out of sight", enables move-in and move-out of individuals to AOI * follow population mode * follow individual mode * day-/night-time visualization * dynamic overplotting, e. g. polygons or points that change over time
**Some day:** * 3D animations, e.g. for including altitude data

moveVis 0.9.8

Updating unit tests for CRAN checks


**Bug fixes:** * Bug causing unit tests to fail on machines with different external tools available * added SystemRequirements field in DESCRIPTION

moveVis 0.9.7

Windows library detection bugs fixed (dev. version)


**New features:** * `time_pos_x` and `time_pos_x` allow to specify the location of the timestamp display * `time_size` allows to specify the font size of the timestamp display * added unit tests
**Bug fixes:** * Bug causing moveVis to not properly detect installed extern libraries that can be called from the command line * Bug causing moveVis to not use conv_dir if it contains a Windows path to a tool of an extern library

moveVis 0.9.6

video support, automatic time harmonization, bug fixes (CRAN version)


**New functions:** * `get_libraries()` – handles all extern libraries that are needed for video formats. Just run it to get information on what you need to install. Replaces get_imconvert(), which can still be called for code compatibility reasons * `get_formats()` – outputs all file formats that can be used with moveVis depending on which libraries are installed on the system.
**New features:** * moveVis supports now multiple video formats in addition to GIF, if it is linked to a video library (either FFmpeg of libav) * animate_move() now detects temporal resolution and uniformity of timestamps automatically to determine, if interpolation needs to be applied to calculate uniform frame times per frame tick * animate_move() now calculates and displays the final animation duration derived from the total number of output frames and the fps prior to generating each frame, so that the user can already approximate which size the output animation will have. * added "frames_tres" to animate_move() to change temporal resolution through linear interpolation * added "frames_pixres" to animate_move() to adjust frame ppi * added "paths_na.hold" to animate_move() for defining how to deal with data gaps (hold or not hold last path location) * added "time_bar_col" to animate_move() for changing colouring of the time bar at the top border of the map * added "out_format" to animate_move() for defining output file format * added "indi_names" to animate_move() for defining individual names vector manually * added "scalebar_dist" to animate_move() for defining the scalebar length manually * added "overwrite" to animate_move() to regulate output file writing behaviour
**Improvements:** * it is now possible to use the 'layer' argument to specify one (static) raster object without specifying 'layer_dt', which is only needed, if several raster objects are handed over as a list. * in some situations, the movement data extent was bigger than the cropped layer extent: this works now * in some situations, stat animation lines were cut off, this should be resolved now * recoding of multiple processing steps to increase processing speed and stability * increased error handler by several errors likely to occure * several bug fixes
**Contributors:** * AniMove 2017 participants

moveVis 0.9.5

adding frames_layout, static_data etc., improvements to workflow


**New features:** * RGB stats support added for animate_stats() and animate_move() * added animate_move() argument "time_scale" to enable a time scale * added animate_move() argument "frame_layout" for user friendly, complex layouting of the output GIF by specifiying the plot locations * added animate_move() argument "layer_stretch" * added animate_move() expert arguments "conv_cmd" and "conv_frames"
**Improvements:** * several major bug fixes * major animate_raster() bug fixes, reenabling use of RGB rasterStack inputs * stats legend is now locatable using frame_layout * fixed a bug of get_imconvert() that caused it to have issues with finding convert.exe on Windows machines, if ImageMagick is preinstalled
**Contributors:** * Bart Kranstauber

moveVis 0.9.4

adding animate_stats() and stats arguments for animate_move()


**New features:** * `animate_stats()` – Enables creation of statistic plot animations visualizing possible relationships between movement paths and basemap. Define individual plot designs based on ggplot2 syntax. * stats arguments for animate_move(): Enables statistic plot animations side-by-side with the spatial plot animation of animate_move. Use the animate_stats() arguments with animate_move(). * extent_factor argument for animate_move(): Increase the distance between the spatial extents of the movement paths and the basemap.
**Improvements:** * Several minor bug fixes

moveVis 0.9.3

fixing major bug


**Improvements:** * Fixed a major bug causing an unavoidable error when creating animations with animate_move() using user defined basemaps (Error message: 'Error in eval(expr, envir, enclos) : Object 'frame_l' not found')

moveVis 0.9.2

adding frame_width and frame_height arguments


**New features:** * Added two new arguments to animate_move() function for changing output frame resolution
**Bug report contributors:** * vestlink (at) github

moveVis 0.9.1

fixing important bug; adding animate_raster()


**New features:** * Added moveStack support: animate_move() now takes also moveStack objects in addition to list objects * `animate_raster()` – for animating just basemaps/for doing the same as with animate_move(), but without movement data
**Improvements:** * Bug fix: Function now takes movebank.org data --> there had been a static code line preventing the read-out of movement coordinates, which is now solved. * Several major and minor bug fixes
**Bug report contributors:** * bart1 (at) github * Patrick Scherler

moveVis 0.9.0

initial release


**Initial features:** * `animate_move()` * `get_imconvert()`
**Initial example data sets:** * data(move_data)

This document should provide a broad overview on changes that are applied to the moveVis R package. There is no warranty for completeness, since minor changes might not be included. All improvement and feature descriptions are bundled per release version. The document is currently maintained by Jakob Schwalb-Willmann.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("moveVis")

0.9.9 by Jakob Schwalb-Willmann, 2 months ago


http://movevis.org


Report a bug at http://www.github.com/16eagle/moveVis/issues


Browse source code at https://github.com/cran/moveVis


Authors: Jakob Schwalb-Willmann [aut, cre]


Documentation:   PDF Manual  


GPL-3 license


Imports maptools, ggplot2, grid, rasterVis, raster, sp, geosphere, rosm, utils, grDevices, methods, stats, move, gridExtra, graphics, simecol, plyr, zoo, lubridate, parallel, pbapply, RStoolbox

Suggests testthat

System requirements: convert from ImageMagick, ffmpeg from FFmpeg


See at CRAN