ARToolKit Professional for iOS release notes

From ARToolworks support library

Main Page > ARToolKit Professional > ARToolKit for iOS > ARToolKit Professional for iOS release notes

Latest release: 2.0.

README

Supplementary read me for ARToolKit Professional v4.5 for iOS, release 2.0.
===========================================================================
Contents.
---------
About this archive.
Requirements.
Getting started.
Release notes.
Next steps.
Notes on the ARApp/ARApp2 design.
About this archive.
------------------- 
This archive contains the ARToolKit Professional libraries, utilities and
examples, version 4.5.2 for iOS, release 2.0.
ARToolKit Professional version 4.5.2 for iOS is released to you under a
proprietary license. Please note that your license terms impose various
restrictions on distribution of ARToolKit in both source and binary forms. Legal
remedy will be sought by ARToolworks, Inc. for any unauthorised distribution.
Please do not attempt to publish your app on Apple's App Store until you have
obtained a valid license from ARToolworks.
Since release 1.0 for iOS, support is provided only for use under iOS v4.0 and
later.
This archive was assembled by:
    Philip Lamb
    ARToolworks, Inc.
    http://www.artoolworks.com
    2011-04-20
Requirements.
-------------
Requirements:
 * Xcode tools v3.2.5 and iOS SDK v4.0 or later, running on Mac OS X 10.6.3 or
later. 
 * An iPhone 3G, iPhone 3GS, iPhone 4, iPod touch 4th Generation, or iPad 2,
running iOS v4.0 or later. Release 2.0 will not run on any earlier versions of
iOS.
 * Paid membership of Apple's iPhone Developer Program (either the $99 standard
program or the $499 enterprise program).
 * A valid iPhone Developer Certificate issued by Apple.
 * A printer to print the pattern PDF images "Hiro pattern", "Kanji pattern",
"Sample1 pattern" and "Sample2 pattern".
ARToolKit Professional v4.5.2 for iOS release 2.0 differs from ARToolKit for
other platforms, in that most of the libraries are supplied in binary-only SDK
form, with additional source for the examples. If you wish to experiment further
with ARToolKit techniques (beyond those provided in the examples) you will also
need to use this iOS release 2.0 alongside a regular full release of ARToolKit
Professional v4.5.2 for Mac OS X, Windows, or Linux.
Getting started.
----------------
The ARToolKit4.xcodeproj file contains three examples of using ARToolKit in an
iOS application.
 * ARApp shows only the most basic usage, which is to track the Hiro marker and
draw a colorcube on the marker.
 * 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.
Later releases of the SDK will demonstrate other techniques including gestural
interaction with the virtual environment, inertial tracking, sound playback and
more, but these basic examples should allow you to put together a development
environment and experiment. If you wish to train more markers, use mk_patt from
another ARToolKit distribution.
Note that the applications will NOT BUILD AND RUN as supplied; you need to
follow the standard procedure for setting up codesigning for an application, as
documented by Apple at
http://developer.apple.com/library/ios/#documentation/Xcode/Conceptual/
iphone_development/128-Managing_Devices_and_Digital_Identities/
devices_and_identities.html. This includes these steps:
1) Obtain a iPhone Developer certificate from Apple.
2) Choose a Bundle ID for the application, e.g. "com.mycompany.myapp" (you can
also use a wildcard ID which can be used to be any application).
3) Using Apple's iPhone Developer portal, generate a provisioning profile
including that Bundle , your iPhone Developer certificate, and the UDIDs of the
devices you wish to test on.
4) Set these settings in the "Build settings" for the ARApp, ARApp2 and ARAppOSG
targets in the Xcode project. I.e. edit the files ARApp-Info.plist,
ARApp2-Info.plist and ARAppOSG-Info.plist, replacing
"com.artoolworks.${PRODUCT_NAME:identifier}" with your Bundle ID.
5) Build the application with code-signing enabled.
Obviously, ARToolKit requires a camera, and cannot be used on the iOS simulator.
If you've never done any iOS development before, this SDK is not the best place
to start. First get some experience with Apple's SDK and build a few of the
examples so that you're familiar with building and running an iOS app on an
actual device. ARToolworks does not typically provide assistance with these
steps.
Release 2.0 release notes.
--------------------------
Improvements:
* Marker-related code is now contained in a new ARMarker class. This and the
ARView class now use NSNotification to communicate with the VirtualEnvironment
class. The former markers.h/markers.c files have been removed, and the format of
the markers.dat file has also changed. This file no-longer contains links to
models; rather, the models link back to markers.
* Full support for filtering of marker poses is now included in the ARMarker
class. Filtering helps remove unwanted high-frequency "jittering" or
"oscillating" of marker poses when the marker pose is poorly conditioned
(typically when the marker is a long distance and/or perpendicular to the camera
line-of-sight). Filtering can be very easily enabled by adding a line "FILTER 1"
to a marker definition in the markers.dat file.
* VirtualEnvironment objects are now separated out into a new VEObject class and
subclasses, which allows for greater customisation of behaviour.
* The arOSG library (which uses OpenSceneGraph) is now fully supported on iOS.
This will allow for loading of models including transform-based animation,
particle effects, custom lighting, and more. More usage notes on use of the OSG
renderer on iOS are available at
http://www.artoolworks.com/support/library/
ARToolKit_for_iOS_libARosg_Release_Notes.
* A new example named ARAppOSG demonstrates use of .osg and .ive files via the
VEObjectOSG class.
* The ARApp2 example has been refactored to use the new ARMarker and VEObjectOBJ
classes. For users who are satisfied with the rendering facilities provided by
ARApp2, it's ongoing use is recommended, as it produces smaller binaries and
fewer memory-related pressues in app design in comparison with ARAppOSG.
* Full support for the iPad 2 has been added to all examples, and the examples
now build as single universal binaries which will load on either iPhones, iPod
touches, or iPads.
* Users can now choose between rear (main) and front cameras, on devices which
have more than one camera, and additionally, can request different resolution
image data from the cameras. Configuration of these options is performed by use
of named parameters to the arVideoOpen() function (in the -start method of the
ARViewController class). See
http://www.artoolworks.com/support/library/
Configuring_video_capture_in_ARToolKit_Professional#AR_VIDEO_DEVICE_IPHONE for
allowable options.
* Camera calibration files are now supplied for specific iOS device models,
including specific calibrations for different focus-distances of the iPhone 4
rear (main) camera, and front cameras on the iPhone 4, iPod touch 4G, and iPad
2. Loading of these camera parameters has also been simplified by addition of
support to libARvideo for requesting the name of a recommended camera parameter
file. If using this facility in your own projects, be sure to include ALL the
camera_para*.dat files included with the example projects, and don't rename
them. Look at the -start method of the ARViewController class for example usage.
Bug fixes:
* A bug whereby no OpenGL content was rendered (a black screen was seen) on
second and subsequent calls to ARViewController's -start method has been fixed.
The fix is a single line (glStateCacheBeginAgain()) in ARView's -init method.
See
http://www.artoolworks.com/community/forum/viewtopic.php?f=22&t=1110&start=15#
p2328 for more info.
* Handling of tearing-down of the ARViewController when it's view is removed
from the active window has been fixed. See
http://www.artoolworks.com/community/forum/viewtopic.php?f=22&t=1110#p1909 for
more info.
* A bug in rendering transparency in Wavefront .obj files has been fixed.
* A bug in handling of badly-formed Wavefront .mtl files has been fixed.
Other notes:
* Unfortunately, Apple's App Store policies are such that iPhone OS v3.1 support
is no longer able to be offered for projects requiring distribution via the App
Store.
Release 1.0 release notes.
--------------------------
Due to the vagaries of Apple's App Store review process, we have temporarily
withdrawn the support for iPhone OS 3.1 which had been provided during the beta
releases. We hope to be able to restore this support in future releases, subject
to some assurances from Apple regarding their App Store review processes. This
change has however had a positive side-effect, which is to simplify the code
paths in the example code. If you already have an App accepted to the App Store
using beta 2.1, and wish to continue to provide 3.1 support, please contact us
for support.
If you have been developing using the 2.1 beta, it is advisable to compare the
example code between this 1.0 release and the beta release in order to see what
code you should change in your own program. A good way to do this is to use the
three-way compare mode of Apple's FileMerge tool. See the instructions at
http://www.artoolworks.com/support/library/
Updating_an_AR_application_with_the_latest_ARToolKit_for_iOS_example_code.
More notes:
* With more iOS-based devices becoming enabled for AR, we have renamed thee kit
to ARToolKit for iOS.
* This release updates the base ARToolKit libraries to ARToolKit Professional
v4.4.3. If you have been developing with the beta releases, you should replace
the ARToolKit headers and library files in your own project with the versions
included in this release.
* A special camera calibration file for the iPhone 4 has been included.
* Support for the iPhone 4's high-resolution display has not yet been included.
We expect to provide this in a future release.
* Preliminary experimental support for the iPod Touch 4G has been provided,
however we do not recommend releasing an app targeting the iPod Touch 4G without
prior testing, as further camera calibration may be required.
* The auto-thresholding features from ARToolKit v4.4.2 and 4.4.3 are enabled by
default on iOS 4.0. If you wish to switch to manual thresholding, locate the
line "//arSetLabelingThreshMode(gARHandle, AR_LABELING_THRESH_MODE_MANUAL)" in
the -start method of ARViewController and remove the comments. Alternately,
manually change the threshold value using arSetLabelingThresh(), as this forces
manual mode.
Next steps.
-----------
We have made a forum for discussion of AR for iOS development available on our
community website.
http://www.artoolworks.com/community/forum/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 products for desktop, web, mobile and
in-app plugin augmented reality. Stay up to date with information and releases
from ARToolworks by joining our announcements mailing list.
http://www.artoolworks.com/Announcements_mailing_list.html
Notes on the ARApp/ARApp2/AppOSG design.
----------------------------------------
ARApp is designed specifically for the iOS environment, and so differs somewhat
from the design that experiened ARToolKit users might expect. It respects the
iOS's model-view-controller design pattern. Calls to ARToolKit's C functions
(part of the "model") are made entirely by the ARViewController class.
ARViewController is a subclass of UIViewController, and is designed to be able
to be reused in your own applications. When instantiated, it opens a video
window, and creates an OpenGL rendering context. When dismissed, it disposes of
the OpenGL context and closes the video window.
As provided, the ARApp example includes a MainWindow NIB file which includes an
instance of the ARViewController class. The application delegate and the
ARViewController are connected in the NIB. You can easily modify this design,
e.g. to load a different view controller when the application is opened. You
could then instantiate ARViewController via a NIB or in code.
The OpenGL drawing code is contained within the ARView class and its superclass
EAGLView. EAGLView is based on Apple sample code and will be familiar to
experienced iOS OpenGL programmers. ARView extends the EAGLView class to provide
important functionality for the AR environment, including compositing the OpenGL
drawing together with the camera image (producing the pincushion rendering
effect). In ARApp, the ARView class just draws a colour cube whenever a valid
camera pose has been set (by the view controller).
In ARApp2 and ARAppOSG, the GL drawing is provided by another object, an
instance of the VirtualEnvironment class (created by the view controller) and
the VEObject/VEObjectOBJ/VEObjectOSG class and subclasses. These apps provides
an example of how a scene graph can be connected to ARToolKit for iOS. ARApp2
makes use of the glm library (significantly extended) to load Wavefront .obj
models, and ARAppOSG adds support for the widely used and full-featured
OpenSceneGraph library.
ARApp2 and ARAppOSG also show more sophisticated techniques for connecting the
ARToolKit marker data to the virtual environment, via use of NSNotification in
the ARView and ARMarker classes. These classes uses NSNotifications to tell the
virtual environment when to update object poses with newly-processed marker
data, and when to draw the updated objects.
It is quite informative to run FileMerge (or some other diff tool) to compare
ARApp and ARApp2's source, particularly the ARViewController and ARView classes.
If you have any further questions about the design, or how the app fits
together, please ask on the community forum (rather than by email) so that
others can benefit from the answers.
--
EOF