tommyteavee / artoolkit5-binary

Read me for ARToolKit for iOS

Contents

• About this archive
• Requirements
• Installing
• Getting started
• Training new markers
• Release notes
• libKPM usage
• Next steps

About this archive

This archive contains the ARToolKit libraries, utilities and examples for iOS, version 5.3.3.

ARToolKit version 5.3.3 is released under the GNU Lesser General Public License version 3, with some additional permissions. Example code is generally released under a more permissive disclaimer; please read the file LICENSE.txt for more information.

If you intend to publish your app on Apple's iOS App Store, you must use your own package name, and not the org.artoolkit package name.

ARToolKit is designed to build on Windows, Macintosh OS X, Linux, iOS and Android platforms.

This archive was assembled by:
Philip Lamb
http://www.artoolkit.org
2016-xx-xx

Requirements

Requirements:

• Xcode tools v5.0.1 or later and iOS SDK v7.0 or later, running on Mac OS X 10.8 or later.
• These devices are supported: iPhone: 4, 4s, 5, 5c, 5s, 6, 6 Plus, 6s, 6s Plus. iPad: 2, 3, Mini, 4, Mini 2, Mini 3, Mini 4, Air, Air 2. iPod touch: 5th Generation. The device must be running iOS 7.0 or later.
• Membership of Apple's iOS Developer Program (free, but paid membership to build for the iOS App Store).
• A valid iOS Developer Certificate issued by Apple.
• A printer to print the pattern PDF images "Hiro pattern", "Kanji pattern", "Sample1 pattern", "Sample2 pattern", and "pinball.jpg".

Installing

ARToolKit is supplied as pre-built binaries for each platform, plus full source code for the SDK libraries, utilities, and examples, and documentation. If you wish to view the source for the desktop-only utilities, you will also need to use this iOS release alongside ARToolKit v5.x for Mac OS X, Windows, or Linux.

The SDK is supplied as an archive file (.tar.gz or .zip file) which need only be unpacked to a location of your choice, e.g. ~/SDKs/. Drop the archive into your chosen location and double-click it in the Finder to unpack it.

Getting started

For full instructions on using this SDK, please refer to the online user guide at http://www.artoolkit.org/documentation/#iOS.

The ARToolKit5.xcodeproj file contains six examples of using ARToolKit in an iOS application.

• ARAppES1 shows only the most basic usage, which is to track the Hiro marker and draw a colorcube on the marker.
• ARApp is identical in functionality to ARAppES1, but uses OpenGL ES 2.0 for rendering.
• ARApp2 shows additional techniques of loading Wavefront .obj models, including textures, from disk, and tracking and drawing on more than one marker. It also includes the required code to perform basic finger-tap interaction with the virtual environment, although this is not currently used in the application.
• ARAppOSG extends the ARApp2 example with loading of models using OpenSceneGraph (.osg and .ive formats) including animation, effects, lighting and more.
• ARAppMovie extends the ARApp2 example with loading and playback of movie file in the 3D virtual environment.
• ARAppNFT shows basic NFT usage, which is to track the "pinball.jpg" image and draw a model (using the Eden Library WaveFront .obj renderer) on the image.
• ARAppNFTOSG shows basic NFT usage, which is to track the "pinball.jpg" image and draw OpenSceneGraph-based models (using the OSG libraries) on the image.

With an appropriate iOS Team Provisioning Profile generated by Xcode, the applications should be able to be built and run directly from the SDK. If however you are basing your own applications on the sample code, you will need to edit the bundle IDs and set up an appropriate provisioning profile for your new bundle ID. I.e. edit the files ARApp*-Info.plist, replacing "org.artoolkit.${PRODUCT_NAME:identifier}" with your Bundle ID. See https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/Introduction/Introduction.html for more info.

ARToolKit cannot be used on the iOS simulator. If you've never done any iOS development before, you will benefit by first getting some experience with Apple's SDK and examples so that you're familiar with building and running an iOS app on an actual device.

Training new markers

The utilities required to train new square and NFT markers are provide in the "bin" directory of the SDK. The utilities are command-line OS X executables which should be run from a Terminal environment.

Consult the ARToolKit documentation for more information:

• http://www.artoolkit.org/documentation/Creating_and_training_new_ARToolKit_markers
• http://www.artoolkit.org/documentation/ARToolKit_NFT

Usage:

• ./mk_patt
• ./genTexData somejpegfile.jpg
• ./dispImageSet somejpegfile.jpg
• ./dispFeatureSet somejpegfile.jpg
• ./checkResolution Data/camera_para.dat (change camera_para.dat to the correct camera calibration file for your device, camera and resolution).

Release notes

This release contains ARToolKit v5.3.3 for iOS.

External API changes in ARToolKit v5.3.3:

arVideoGetImage now returns a pointer to an AR2VideoBufferT structure. Previously it returned a raw pointer to a pixel buffer. The buffer is valid until the next call to arVideoGetImage, or until the video stream is stopped and/or closed with a call to arVideoCapStop or arVideoClose. This API is now consistent with the ar2VideoGetImage call.

    From:  ARUint8 *arVideoGetImage(void);
    To: AR2VideoBufferT *arVideoGetImage(void);

Note that the minimum supported structure of returned video images have changed. The only guaranteed channel now is a luminance channel. For video modules that cannot provide a luma channel readily internally, accelerated ARM, ARM64 and x86 SSE routines perform an optimized conversion from 32-bit RGBA formats internally to ar2VideoGetImage.

Correspondingly, the API for arDetectMarker has changed. It now accepts a pointer to an AR2VideoBufferT structure, rather than a raw pointer to a pixel buffer.

    From: int arDetectMarker(ARHandle *arHandle, ARUint8 *dataPtr);
    To: int arDetectMarker(ARHandle *arHandle, AR2VideoBufferT *frame);

Additionally, the API for a number of internal ARToolKit functions has changed to reflect the expectation that these functions will be supplied with a luminance-only buffer. Several functions in libKPM reflect this change.

The major change in ARToolKit v5.3 was a new version of libKPM based on the FREAK detector framework, contributed by DAQRI. See "libKPM usage" below.

Please see the ChangeLog.txt for details of changes in this and earlier releases.

ARToolKit v5.2 was the first major release under an open source license in several years, and represented several years of commercial development of ARToolKit by ARToolworks during this time. It was a significant change to previous users of ARToolKit v2.x. Please see http://www.artoolkit.org/documentation/ARToolKit_feature_comparison for more information.

For users of ARToolKit Professional versions 4.0 through 5.1.7, ARToolKit v5.2 and later include a number of changes. Significantly, full source is now provided for the NFT libraries libAR2 and libKPM.

libKPM usage

libKPM, which performs key-point matching for NFT page recognition and initialization now use a FREAK detector framework, contributed by DAQRI. Unlike the previous commercial version of libKPM which used SURF features, FREAK is not encumbered by patents. libKPM now joins the other core ARToolKit libraries under an LGPLv3 license. Additionally the new libKPM no longer has dependencies on OpenCV’s FLANN library, which should simply app builds and app distribution on all supported platforms.

Existing holders of a commercial license to ARToolKit Professional v5.x may use libKPM from ARToolKit v5.2 under the terms of their current license for the remainder of its duration. Please contact us via http://www.artoolkit.org/contact if you are an existing user of ARToolKit Professional with questions.

Next steps

We have made a forum for discussion of ARToolKit for iOS development available on our community website.

http://www.artoolkit.org/community/forums/viewforum.php?f=22

You are invited to join the forum and contribute your questions, answers and success stories.

ARToolKit consists of a full ecosystem of SDKs for desktop, web, mobile and in-app plugin augmented reality. Stay up to date with information and releases from artoolkit.org by joining our announcements mailing list.(Click ‘Subscribe’ at the bottom of http://www.artoolkit.org/)

Do you have a feature request, bug report, or other code you would like to contribute to ARToolKit? Access the complete source and issue tracker for ARToolKit at http://github.com/artoolkit/artoolkit5