Transform Flow is a library for processing and analysing mobile phone sensor data and video streams. It uses an abstract motion model class to expose various tracking and registration algorithms, and these models can either be applied to static data sets or in real time on a mobile device.
There are a number of ways to contribute to this project:
- Support more platforms, primarily Android and Linux, but potentially Windows in the future.
- Develop motion models, including designing a motion model which reconciles global and local tracking approaches.
- Better automatic evaluation of motion models in the visualisation tool.
Transform Flow is a C++ library for the development of outdoor augmented reality tracking algorithms. It includes a data capture and visualisation tool, as well as a browser application for using the algorithms in real time:
- Transform Flow
- Transform Flow Capture for iOS
- Transform Flow Capture for Android (incomplete)
- Transform Flow Data Sets
- Transform Flow Visualisation
- Transform Flow Browser for iOS
- Transform Flow Browser for Android (incomplete)
Currently the main development platform is Mac OS X and iOS, but we are expanding this to include Linux and Android.
Use teapot to build Transform Flow. You will need Ruby 1.9.3+ (preferably 2.0+) to install:
$ gem install teapot
Once you've downloaded source code, build as follows:
$ cd transform-flow
$ export OSX_SDK_VERSION=10.8
$ teapot fetch
$ teapot build Library/TransformFlow variant-debug
For your own projects, you are best to use teapot as it can automatically fetch, build and link your code against TransformFlow. See teapot.rb in Transform Flow Visualisation for an example.
Transform Flow provides a set of classes for interacting with static data sets:
Path data_path = "path/to/data-set";
Ref<MotionModel> motion_model = new BasicSensorMotionModel;
Ref<VideoStream> video_stream = new VideoStream(data_path, motion_model);
auto frames = video_stream->frames()
log_debug("Heading", frames[0].heading, "Gravity", frames[0].gravity);
The best place to see a working example is in the code for the Transform Flow Visualisation application.
The video stream format consists of a directory of images and a CSV log file.
The CSV format is as follows:
[sequence-number],[event-name],[event-arguments,]
There are several pre-defined events:
const char * GYROSCOPE = "Gyroscope";
const char * ACCELEROMETER = "Accelerometer";
const char * GRAVITY = "Gravity";
const char * MOTION = "Motion";
const char * LOCATION = "Location";
const char * HEADING = "Heading";
const char * FRAME = "Frame";
The motion event is a group of device sensor information at a single timestamp. It currently includes the Gyroscope, Accelerometer and Gravity events with the same timestamp and typically takes the form:
1,Gyroscope,[timestamp],[rotation.x],[rotation.y],[rotation.z]
2,Accelerometer,[timestamp],[acceleration.x],[acceleration.y],[acceleration.z]
3,Gravity,[timestamp],[gravity.x],[gravity.y],[gravity.z]
4,Motion,[timestamp]
The timestamp SHOULD be the same value for grouped motion events.
The location event typically represents an update from the GPS and includes the position and accuracy of the update:
1,Location,[timestamp],[latitude],[longitude],[horizontal_accuracy],[vertical_accuracy]
The heading event typically represents an update from the compass. It includes both the magnetic north and true north.
1,Heading,[timestamp],[magnetic_bearing],[true_bearing]
The frame event represents a camera frame captured and includes data as an external PNG file in the same directory as the log file.
1,Frame,[timestamp],[index]
The file in this case would be called [index].png.
It is useful to log device specific information and frame rates. These are currently not used directly by the visualisation tool, but may be in the future.
1,Device,[device_name],[device_model],[system_version]
This record is normally logged at the start of the capture.
Additional records relating to configuration may be included (e.g. frame rates, sensor rates) but these are for informational purposes at this time.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
Released under the MIT license.
Copyright, 2013, by Samuel G. D. Williams.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.