/pmaToolkit

A framework to navigate through the Museum using iBeacons. Made available to kickstart location-based projects for the first-ever hackathon at the Philadelphia Museum of Art.

Primary LanguageSwift

pmaToolkit

Requirements

  • iOS 8.0+
  • Xcode 7.2+ - CocoaPods

Before you start

The Philadelphia Museum of Art is committed to making its collection data available for public access. Whilst we have a web interface for searching the collection, we are now also making our dataset of works in the public domain available for free public download.

#Usage guidelines The Philadelphia Museum of Art (the "Museum") provides www.philamuseum.org and its subdomains (the "Websites") and any third-party hosted site which is supplied with content by the Museum, such as github.com/philamuseum in support of the Museum's mission. In brief, the Museum’s mission is to preserve, enhance, interpret, and extend the reach of its great collections in particular, and the visual arts in general. By accessing the Websites and any third-party hosted site which is supplied with content by the Museum, such as github.com/philamuseum, users agree to be bound by the following terms and conditions, which the Museum may revise from time to time. Users are encouraged to visit this page periodically to review current terms and conditions.

WEBSITE CONTENT IS PROTECTED BY LAW. The data, images, software, documentation, text, video, audio, and other information on the Websites (the "Materials") are proprietary to the Museum or its licensors or other third parties. The Museum retains all its rights, including copyright, in the Materials. Copyright and other proprietary rights may be held by individuals or entities other than, or in addition to, the Museum. Any unauthorized use of the Materials or the Trademarks (defined below), except as permitted by these terms and conditions, is strictly prohibited. PERMITTED USE. The Materials are made available for non-commercial, educational and personal use only or for "fair use" under the United States copyright laws. Users may download files for personal use, subject to any additional terms or restrictions applicable to the individual Materials. Users must properly cite the source of the Materials and the citations should include a link to www.philamuseum.org. By downloading, printing, or using Materials from the Websites, whether accessed directly or indirectly, users agree that they will limit their use to the uses permitted by these terms and conditions or by fair use, and will not violate the Museum’s or any other party's proprietary rights. Users may not remove any copyright, trademark, or other proprietary notices and may not modify the Materials. Downloading, copying, distributing, or otherwise using Materials for any commercial purpose is strictly prohibited. NO WARRANTIES. The Museum does not warrant or represent that use of Materials displayed on the Website will not infringe the rights of third parties. ALL MATERIALS ON THE WEBSITES ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY , FITNESS FOR PARTICULAR PURPOSE, COPYRIGHT OWNERSHIP AND NON-INFRINGEMENT. The Museum will not be liable for any damages to or viruses that may infect a user’s computer or other device resulting from use of any Websites or from downloading any Materials. At its discretion, the Museum may discontinue or take down all or any part of the Websites or remove any Material at any time. LICENSING. Anyone wishing to use any Materials for other than a permitted use must receive prior permission. To obtain permission (a license), please contact:

The Philadelphia Museum of Art Library and Archives Tel: 215-684-7650 E-mail: library@philamuseum.org

DIGITAL MILLENNIUM COPYRIGHT ACT ("DMCA"). The Museum is committed to complying with U.S. copyright and related laws, and requires all users of the Websites to comply with these laws. Owners of copyrighted works who believe that their rights under U.S. copyright law have been infringed should report their concern by providing notice to the Museum’s Designated Agent pursuant to DMCA. If notice is provided by email, please send the notice to: library@philamuseum.org. If notice is provided by mail, please send the notice to: Designated Copyright Agent, c/o General Counsel, Philadelphia Museum of Art, P.O. Box 7646, Philadelphia, PA 19101-7646. TRADEMARKS. Many of the trademarks, service marks and logos ("Trademarks") displayed on the Websites, including PHILADELPHIA MUSEUM OF ART, RODIN MUSEUM and PMA, are marks of the Philadelphia Museum of Art which are registered or otherwise protected by law. The Trademarks of third parties may also be displayed on the Websites. Nothing contained in the Websites should be construed as granting any license or right to use any Trademark without written permission of the Museum or third party that may own the Trademark.

##Give attribution to the Philadelphia Museum of Art Make sure that others are aware of the rights status of the Philadelphia Museum of Art and are aware of these guidelines by keeping intact links. If for technical or other reasons you cannot include all the links to all sources of the Metadata and rights information directly with the Metadata, you should consider including them separately, for example in a separate document that is distributed with the Metadata or dataset. If for technical or other reasons you cannot include all the links to all sources of the Metadata and rights information, you may consider linking only to the Metadata source on the Philadelphia Museum of Art’s website, where all available sources and rights information can be found, including in machine readable formats. ##Metadata is dynamic When working with Metadata obtained from the Philadelphia Museum of Art, please be aware that this Metadata is not static. It sometimes changes daily. The Philadelphia Museum of Art continuously updates its Metadata in order to correct mistakes and include new and additional information. Museum collections are under constant study and research, and new information is frequently added to objects in the collection. ##Pull requests Because these datasets are generated from our internal database, we do not accept pull requests. If you have identified errors or have extra information to share, please email us at Laura.Webb@philamuseum.org and we will forward to the appropriate department for review. ##No endorsement Use of this dataset does not grant or imply PMA’s approval, commission, or support of your work. PMA retains the rights to all of its trademarks, and they are not part of the dataset. Ensure that you do not use the Metadata in a way that suggests any official status or that the Philadelphia Museum of Art endorses you or your use of the Metadata, unless you have prior permission to do so. If you transform or modify to the dataset, you must clearly distinguish the resulting work as having been modified from the PMA dataset. If you create a derivative dataset from the PMA dataset, we ask that you consider releasing the derivative under a CC0 license.

##Ensure that you do not mislead others or misrepresent the Metadata or its sources Ensure that your use of the Metadata does not breach any national legislation based thereon, notably concerning (but not limited to) data protection, defamation or copyright. Please note that you use the Metadata at your own risk. The Philadelphia Museum of Art offers the Metadata as-is and makes no representations or warranties of any kind concerning any Metadata published by the Philadelphia Museum of Art. ##The writers of these guidelines are deeply indebted to the Tate, MoMA, Smithsonian Cooper-Hewitt, National Design Museum; and Europeana.

Getting started

Install CocoaPods (if not already installed)

$ gem install cocoapods

Add to your Podfile:

  platform :ios, '8.0'
  use_frameworks!

  pod 'SwiftyJSON', :git => ‘https://github.com/SwiftyJSON/SwiftyJSON.git'
  pod 'pmaToolkit', :git => ‘https://github.com/philamuseum/pmaToolkit.git '

Then run pod install

$ pod install

Configuration

In order for the framework to work, the following information has to be supplied:

  • iBeacon UUID
pmaToolkit.settings.iBeaconUUID ={Your UUID}
  • Remote Location & iBeacon definitions
pmaToolkit.settings.cacheSettings.hostProtocol = “https” 
hostname = “yourhost.com” 
urlBeacons =/path/to/beacons.json” 
urlLocations =/path/to/locations.json”

Features

Heading

The framework outputs the current heading in 10 degree steps as a NSNotification (didUpdateHeading). There are two values that come along with the notification for an updated heading: actualHeadingDegrees and calculatedHeadingRadians, with the latter already converted for the actual orientation of the building.

Ranging beacons

The following NSNotification-based notifications are being sent:

  • locationChanged with currentLocation as pmaLocation This event will only be sent in case a location change happened, in other words, it will not fire while a user stays in the same space in a gallery (except if that location happens to be at the intersection of two galleries, so the signal could bounce)
  • locationUnknown with lastKnownLocation as? pmaLocation (optional, can be nil) This notification is only sent every 30s in case no location can be determined. Since we placed our beacons at the entrance ways of a gallery, it can certainly happen that the device looses its signal. This event should be treated with care for this reason.

Logging

The framework has four log levels with 4 being the most verbose. By default, it is set to 3. If you want to make changes, use pmaToolkit.settings.logLevel = X. To use the supplied logger, simply call

pmaToolkit.logDebug("") 
pmaToolkit.logInfo("") 
pmaToolkit.logError("")