Location, motion, and activity recording framework for iOS
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
LocoKit Demo App.xcodeproj updated demo app's lock file to point at 5.2.0 Apr 29, 2018
LocoKit Demo App.xcworkspace updated the Demo App for Xcode 9.3 and LocoKit 5.1.1 Apr 2, 2018
LocoKit Demo App point the demo app podfile at ios 10.0 deploy target instead of 11.0 Apr 29, 2018
LocoKit don't re-sort the segment samples array on every addition. too expensive Apr 29, 2018
LocoKitCore.framework random attempt to fix the new mystery Xcode pod architectures error Apr 29, 2018
Screenshots a couple of boring examples, until i get out of the house tomorrow an… Oct 13, 2017
docs renamed ArcKit to LocoKit, and prep for 5.0 release Mar 17, 2018
.gitignore screenshots for readme Jul 26, 2017
.swift-version sigh. CocoaPods still seems to need this swift-version file, even tho… Dec 20, 2017
ActivityTypeClassifierExamples.md apparently new lines are significant in markdown tables. who knew Oct 13, 2017
ArcKit.podspec misc timeline manager / store bug fixes and improvements Mar 9, 2018
ArcKitCore.podspec SQLite based local store for TimelineItems and LocomotionSamples Jan 28, 2018
BackgroundLocationMonitoring.md Update ReadMe to include background location monitoring Jun 27, 2018
CHANGELOG.md updated changelog for 5.2.0 Apr 29, 2018
LICENSE changed license from ambiguous "commercial" to LGPL Jul 6, 2018
LocationFilteringExamples.md more readme tweaks, and prep for activity type classifier examples doc Oct 13, 2017
LocoKit.podspec updated podspecs for 5.2.0 Apr 29, 2018
LocoKitCore.podspec updated podspecs for 5.2.0 Apr 29, 2018
Podfile point the demo app podfile at ios 10.0 deploy target instead of 11.0 Apr 29, 2018
Podfile.lock updated demo app's lock file to point at 5.2.0 Apr 29, 2018
README.md added Patreon to the readme Jul 6, 2018
TimelineItemDescription.md Update ReadMe to include background location monitoring Jun 27, 2018

README.md

LocoKit

A Machine Learning based location recording and activity detection framework for iOS.

Location and Motion Recording

  • Combined, simplified Core Location and Core Motion recording
  • Filtered, smoothed, and simplified location and motion data
  • Near real time stationary / moving state detection
  • Automatic energy use management, enabling all day recording
  • Automatic stopping and restarting of recording, to avoid wasteful battery use

Activity Type Detection

  • Machine Learning based activity type detection
  • Improved detection of Core Motion activity types (stationary, walking, running, cycling, automotive)
  • Distinguish between specific transport types (car, train, bus, motorcycle, airplane, boat)

Record High Level Visits and Paths

  • Optionally produce high level Path and Visit timeline items, to represent the recording session at human level. Similar to Core Location's CLVisit, but with much higher accuracy, much more detail, and with the addition of Paths (ie the trips between Visits).
  • Optionally persist your recorded samples and timeline items to a local SQL based store, for retention between sessions.

More information about timeline items can be found here

Supporting the Project

LocoKit is an LGPL licensed open source project. Its ongoing development is made possible thanks to the support of its backers on Patreon.

If you have an app that uses LocoKit and is a revenue generating product, please consider sponsoring LocoKit development, to ensure the project that your product relies on stays healthy and actively maintained.

Thanks so much for your support!

Installation

pod 'LocoKit'
pod 'LocoKit/LocalStore' # optional

Note: Include the optional LocoKit/LocalStore subspec if you would like to retain your samples and timeline items in the SQL persistent store.

High Level Recording

Record TimelineItems (Paths and Visits)

// retain a timeline manager
self.timeline = TimelineManager()

// start recording, and producing timeline items 
self.timeline.startRecording()

// observe timeline item updates
when(timeline, does: .updatedTimelineItem) { _ in
    let currentItem = timeline.currentItem

    // duration of the current Path or Visit
    print("item.duration: \(currentItem.duration)")

    // activity type of the current Path (eg walking, cycling, car)
    if let path = currentItem as? Path {
        print("path.activityType: \(path.activityType)")
    }

    // examine each of the LocomotionSamples within the Path or Visit
    for sample in currentItem.samples {
        print("sample: \(sample)")
    }
}

Low Level Recording

Record LocomotionSamples (CLLocations combined with Core Motion data)

// the recording manager singleton
let loco = LocomotionManager.highlander
// decide which Core Motion features to include
loco.recordPedometerEvents = true
loco.recordAccelerometerEvents = true
loco.recordCoreMotionActivityTypeEvents = true
// decide whether to use "sleep mode" to allow for all day recording 
loco.useLowPowerSleepModeWhileStationary = true

Note: The above settings are all on by default. The above snippets are unnecessary, and just here to show you some of the available options.

// start recording 
loco.startRecording()
// watch for updated LocomotionSamples
when(loco, does: .locomotionSampleUpdated) { _ in

    // the raw CLLocation
    print(loco.rawLocation)

    // a more usable, de-noised CLLocation
    print(loco.filteredLocation)

    // a smoothed, simplified, combined location and motion sample
    print(loco.locomotionSample())
}

Fetching TimelineItems / Samples

If you wanted to get all timeline items between the start of today and now, you might do this:

let date = Date() // some specific day
let items = store.items(
        where: "deleted = 0 AND endDate > ? AND startDate < ? ORDER BY endDate",
        arguments: [date.startOfDay, date.endOfDay])

You can also construct more complex queries, like for fetching all timeline items that overlap a certain geographic region. Or all samples of a specific activity type (eg all "car" samples). Or all timeline items that contain samples over a certain speed (eg paths containing fast driving).

Detect Activity Types

Note that if you are using a TimelineManager, activity type classifying is already handled for you by the manager, on both the sample and timeline item levels. You should only need to directly interact with clasifiers if you are either not using a TimelineManager, or are wanting to do low level processing at the sample level.

// fetch a geographically relevant classifier
let classifier = ActivityTypeClassifier(coordinate: location.coordinate)

// classify a locomotion sample
let results = classifier.classify(sample)

// get the best match activity type
let bestMatch = results.first

// print the best match type's name ("walking", "car", etc)
print(bestMatch.name)

Note: The above code snippets use SwiftNotes to make the event observing code easier to read. If you're not using SwiftNotes, your observers should be written something like this:

let noteCenter = NotificationCenter.default
let queue = OperationQueue.main 

// watch for updates
noteCenter.addObserver(forName: .locomotionSampleUpdated, object: loco, queue: queue) { _ in
    // do stuff
}

Background Location Monitoring

If you want the app to be relaunched after the user force quits, enable significant location change monitoring.

More details and requirements here

Examples and Screenshots

Documentation

Try the LocoKit Demo App

  1. Download or clone this repository
  2. pod install
  3. In Xcode, change the Demo App project's "Team" to match your Apple Developer Account
  4. In Xcode, change the Demo App project's "Bundle Identifier" to something unique
  5. Build and run!
  6. Go for a walk, cycle, drive, etc, and see the results :)

Try Arc App on the App Store

  • To see the SDK in action in a live, production app, install Arc App from the App Store, our free life logging app based on LocoKit