- Brief reports
- Open Access
Superplot3d: an open source GUI tool for 3d trajectory visualisation and elementary processing
Source Code for Biology and Medicine volume 8, Article number: 19 (2013)
When acquiring simple three-dimensional (3d) trajectory data it is common to accumulate large coordinate data sets. In order to examine integrity and consistency of object tracking, it is often necessary to rapidly visualise these data. Ordinarily, to achieve this the user must either execute 3d plotting functions in a numerical computing environment or manually inspect data in two dimensions, plotting each individual axis.
Superplot3d is an open source MATLAB script which takes tab delineated Cartesian data points in the form x, y, z and time and generates an instant visualization of the object’s trajectory in free-rotational three dimensions. Whole trajectories may be instantly presented, allowing for rapid inspection. Executable from the MATLAB command line (or deployable as a compiled standalone application) superplot3d also provides simple GUI controls to obtain rudimentary trajectory information, allow specific visualization of trajectory sections and perform elementary processing.
Superplot3d thus provides a framework for non-programmers and programmers alike, to recreate recently acquired 3d object trajectories in rotatable 3d space. It is intended, via the use of a preference driven menu to be flexible and work with output from multiple tracking software systems. Source code and accompanying GUIDE .fig files are provided for deployment and further development.
Comparatively recent developments in object trajectory capture allow easy acquisition of three-dimensional (3d) flight data from moving objects by capturing output from two fixed position cameras with overlapping x and y axes and applying on-the-fly conversion to Cartesian xyz co-ordinates [1–6]. One such commercially available tracking solution is Trackit 3D (SciTrackS, GmbH) . Trackit 3D allows the trajectories of very small objects to be tracked, including those of very small insects [3, 7, 8].
In an ordinary tracking event using a standard PAL analogue camera at 25 frames s-1, Trackit 3D utilises the 2 fields contained within each frame. Irrespective of whether tracking is correct, one second of recorded output equates to 50 textual lines of data with each line intended to represent the current position of the object being tracked. Acquisition of flight data by this method rapidly generates vast sets of Cartesian output that necessitates the use of 3d visualisation in order to make it meaningful and ensure tracking integrity remains consistent. For example, in a real world scenario, 22 minutes of insect tracking will create output that exceeds the bounds of an .xls file (65,536 rows). Whilst it is easy to interrogate such data with the plot3 command in MATLAB (The Mathworks, MA) or a free equivalent numerical computing environment such as GNU Octave , doing so provides very basic output and necessitates that the user apply specific syntax in order to format or interrogate plotted output or alter which points are plotted. Whilst this may be suitable for a short trajectory, it becomes increasingly arduous when the track duration is over several minutes or indeed if only a few seconds of the track are of interest. In addition, further analysis in such an environment requires considerable familiarisation with MATLAB or Octave.
Superplot3d allows a user with no previous MATLAB experience to instantly inspect large datasets of flight trajectory where data is provided as x, y, z and time. The software uses MATLAB’s underlying painters rendering engine along with calls to Matlab graphical user interface functions to output the complete object trajectory, or subsets of it. Trajectory view is auto-scalable or user definable using menu-driven preferences. The user is able to free-rotate the trajectory in three dimensions, select key sections to view and convert regions from Cartesian to cylindrical polar coordinates for further analysis. The speed, idiothetic 3d turning angle and vector reference heading of the tracked object can also be derived. In addition, it is easy to split the trajectory at the point at which an interruption to the tracking data occurs, producing multiple subsets of a tracked trajectory. This enables the user to rapidly gauge the value of the data as a whole, and of its constituent parts. See Figures 1, 2, 3, 4 for an overview.
Furthermore, inclusion of the source code and accompanying GUIDE .fig file allow the user to readily modify this program as necessary.
Methods and implementation
Superplot3d is a platform independent MATLAB .m file (available under creative commons license from http://superplot3d.slu.se) compatible with MATLAB R2010a (R14) and above. Moreover, if the MATLAB compiler toolkit is present on the development machine, it is deployable as a standalone executable. This allows a small self-contained application to be built enabling users with the appropriate MATLAB Compiler Runtime (MCR) installed on their system to use all functions without having a MATLAB installation present. Any built application is thus designed to neatly co-exist with the track acquisition software on the data acquisition workstation, allowing for near instantaneous trajectory inspection.
Data provided as tab delimited, or comma separated files may be read directly into memory. Data are error checked for obvious anomalies (mismatched matrix dimensions) and prolonged periods of tracking loss are truncated to one line between tracks. Said data are passed to a process function, which after being indexed by user defined variables (defined in the preference menu), generates a structure containing processed data output. Whole data may be visualised with a press of a button. In addition, tracking may be viewed from subsequent user defined points, the entire set of tracks may be split up at breaks in tracking where one or more NaN is returned, the entire dataset can be viewed as cylindrical polar coordinates and the user may be able to select specific tracks, 'cutting’ them, accordingly. Outputted data may be returned as a .csv file containing columns containing x, y, z, t, distance between tracked point 1 and tracked point 2, distance between tracked point 1 and tracked point 3, speed, idiothetic turning angle and 3d angle in relation to a definable reference vector. Calculations are illustrated in Table 1.
Superplot3d is a framework for rapidly evaluating object trajectory data. It is designed to form a platform for further development and in itself provides a useful tool for trajectory examination. It has been used for real world mosquito flight trajectory data at the Gibson laboratory, Natural Resources Institute, University of Greenwich UK.
IAND is a postdoctoral research fellow in chemical ecology at the Swedish University Of Agricultural Sciences, SLU Alnarp. LW is a visual effects artist and physics graduate. FMH is a postdoctoral research fellow at the University of Greenwich.
Hardie J, Young S: Aphid flight-track analysis in three dimensions using video techniques. Physiol Entomol. 1997, 22: 116-122. 10.1111/j.1365-3032.1997.tb01148.x.
El-Sayed A, Gödde J, Arn H: A computer-controlled video system for real-time recording of insect flight in three dimensions. J Insect Behav. 2000, 6: 881-900.
Fry S, Bichsel M, Müller P, Robert D: Tracking of flying insects using pan-tilt cameras. Neurosci Meth. 2000, 101: 59-67. 10.1016/S0165-0270(00)00253-3.
Cooperband M, Cardé R: Orientation of Culex mosquitoes to carbon dioxide- baited traps: flight manoeuvres and trapping efficiency. Med Vet Entomol. 2006, 20: 11-26. 10.1111/j.1365-2915.2006.00613.x.
Spink A, Ballintijn M, Bogers N, Grieco F, Loijens L, Noldus L, Smit G, Zimmerman P: Proceedings of Measuring Behavior 2008. 2008, The Netherlands: Maastricht
Butail S, Manoukis NC, Diallo M, Ribeiro JMC, Lehmann T, Paley DA: The dance of male Anopheles gambiae in wild mating swarms. J Med Entomol. 2013, 50: 552-559. 10.1603/ME12251.
Müller P, Robert D: A shot in the dark: the silent quest of a free-flying phonotactic fly. J Exp Biol. 2001, 204: 1039-1052.
Müller P, Robert D: Death comes suddenly to the unprepared: singing crickets, call fragmentation, and parasitoid flies. Behav Ecol. 2002, 13 (5): 598-606. 10.1093/beheco/13.5.598.
GNU Octave: Network Theory Limited. 2002,http://www.gnu.org/software/octave.
A previous non-GUIDE based version of this program was written by IAND to process mosquito flight data at the lab of Dr G Gibson (Natural Resources Institute) and Prof IJ Russell (University of Brighton). This project was thus partially funded by a BBSRC grant (BB/F003307/1) awarded to GG and IJR. IAND would like to thank both for their support during this time. We would also like to thank Dr S Young (Natural Resources Institute) for contributing idiothetic 3d turning angle code which was ported to MATLAB by IAND and LW. We thank A Pakyari (SLU Uppsala) for facilitating online hosting of this project. Lastly, we thank two anonymous reviewers for their valuable comments on the manuscript.
The authors declare that they have no competing interests.
IAND and LW developed the software from IAND’s initial code. IAND, FMH and LW wrote the manuscript. All authors have read and approved the final manuscript.
About this article
Cite this article
Whitehorn, L.J., Hawkes, F.M. & Dublon, I.A. Superplot3d: an open source GUI tool for 3d trajectory visualisation and elementary processing. Source Code Biol Med 8, 19 (2013). https://doi.org/10.1186/1751-0473-8-19