ARToolKit Professional for iOS release notes

From ARToolworks support library

Jump to: navigation, search

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

Latest release: 24.



Supplementary read me for ARToolKit Professional for iOS, release 24.
About this archive.
Getting started.
Training new markers.
Release notes.
Next steps.
Notes on the ARApp design.
About the camera.
About this archive.
This archive contains the ARToolKit Professional libraries, utilities and
examples for iOS, release 24.
ARToolKit Professional 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.
This archive was assembled by:
    Philip Lamb
    ARToolworks, Inc.
 * Xcode tools v4.5 or later and iOS SDK v6.0 or later, running on Mac OS X 10.7
or later.
 * These devices are supported: iPhone: 3GS, 4, 4s, 5, 5c, 5s. iPad: 2, 3, Mini,
4. iPod touch: 4th Generation, 5th Generation. The device must be running iOS
4.3 or later. The iPhone 3GS is not supported for NFT use.
 * Paid membership of Apple's iOS Developer Program.
 * 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".
ARToolKit Professional for iOS differs from ARToolKit for other platforms, in
that most of the libraries and utilities 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 might wish to
use this iOS release alongside a release of ARToolKit Professional 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.
The ARToolKit5.xcodeproj file contains six examples of using ARToolKit in an iOS
 * 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
 * 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.
See the in
ARToolworks' support library for more information on the design of these apps.
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, ARApp2-Info.plist,
ARAppOSG-Info.plist and ARAppMovie-Info.plist, replacing
"com.artoolworks.${PRODUCT_NAME:identifier}" with your Bundle ID. See
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. ARToolworks does not typically provide assistance
with these steps.
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 Mac OS X executables
which should be run from a Terminal environment.
Consult the ARToolworks support library for more information:
	./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 Professional v5.0.5 for iOS. Please see the
ChangeLog.txt for details of changes in this and earlier releases.
The following major changes in ARToolKit version 5 are discussed in detail
*	New NFT dataset format.
*	Support for optimised bi-planar video formats.
*	OpenGL ES 2.0 support.
*	Improved support for stereo and see-through displays.
* New NFT dataset format *
ARToolKit version 5.0 introduces a new (non-backwards compatible) improved NFT
dataset format. While most of the APIs and tools for NFT tracking remain
identical, performance has been improved and dataset sizes have been
dramatically reduced, typically by more than 90%. As an example, the “pinball”
sample NFT dataset (high-resolution A4 size) included with ARToolKit v4.x has
shrunk from a total of 4.4MB to 324KB. An A5-size dataset at lower resolution
can be shrunk to under 100KB. This change comes with the same level of tracking
performance. We believe this will make both local storage and over-the-air
transmission of NFT datasets far more comfortable for developers.
To take advantage of the new format, upgrade your application code to the sample
code included with ARToolKit v5, link against the new version of the ARToolKit
libraries, and re-run your dataset generation on the same original images.
* Support for optimised bi-planar video formats *
The capture, processing and display of video from the camera is a significant
load on a typical AR application. That’s why we’ve put a lot of effort into
improving performance in this area, especially on iOS and Android. Full support
for optimised bi-planar YCbCr image formats is now throughout the toolkit,
including acquisition by libARvideo, processing by libAR, libAR2 and libKPM, and
display by libARgsub_es. The result is lower I/O, CPU and memory bus bandwidth
requirements, reduced memory usage, improved tracking performance, and
consequent reduced CPU usage and improved battery life on mobile devices.
The default format for iOS apps is now AR_PIXEL_FORMAT_420f, and for Android
apps AR_PIXEL_FORMAT_NV21. If developers still need RGBA pixels, e.g. for
screen-capture purposes, it is trivial to request this instead with the
“-format=” video configuration string token.
* OpenGL ES 2.0 support *
Support for OpenGL ES 2.0 has been added… finally! A new version of the GL
integration library, libARgsub_es2, provides support for video see-through
rendering, and utility functions to support a programmable OpenGL pipeline
including shader management and matrix manipulation. The iOS app ARApp and the
Android app ARNative have been updated to ES2, while the same apps are also
available targeting ES1 (as ARAppES1 and ARNativeES1, respectively) to allow
developers to compare and contrast the changes required.
Further ES2 support will progressively be added to the toolkit, including in the
OSG-based examples, and the glm renderer. However, the new support provides the
groundwork for developers to use ES 2 or integrate their existing ES 2-based
code into an ARToolKit-based app.
* Improved support for stereo and see-through displays *
One of the strengths of ARToolKit is its adaptability to a wide range of
different hardware configurations. ARToolKit has for some time been unique in
its support for tracking with stereo cameras. In version 5, as well as
continuing to support ARToolKit’s stereo tracking, the stereo example now
supports a variety of different stereo display configurations, including:
dual-output, quadbuffered/frame-sequential, side-by-side, over-under (and
half-width/half-height variants), and more.
ARToolKit’s support for see-through head-mounted displays (HMDs) is greatly
improved in ARToolKit version 5 too. The calib_optical utility has been made
easier to use, and can also be used with stereo see-through HMDs while tracking
with a single camera. The optical and stereoOptical examples also now provide
high-quality rendering via OSG.
* For much more detail of changes in this and earlier releases please see the
file ChangeLog.txt. *
Next steps.
We have made a forum for discussion of AR for iOS development available on our
community website.
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.


ARToolKit Professional ChangeLog.
Changes in version 5.0.5 (this release) (2014-01-06).
- arImageProcMode is now exposed through libARWrapper.
- Numerous small API documentation improvements.
- EdenSound interface is now provided, connecting to OpenAL.
- Android: the CameraPreferences API now allows querying of whether the camera
is front-facing.
- Added arUtilGetFileExtensionFromPath().
- In threading library, added extra function threadGetBusyStatus to test if a
thread is between start and end states.
- gluttext is now in libEden.
- calib_camera will use arImageProcLuma to do grayscale conversion, improving
- Added a parameter to arImageProcInit to force copying of incoming image, even
if mono, to handle case where we might need to keep the image around for longer.
- ARWrapper internal improvements.
- Windows: The DSVideoLib library (used with video config '-device=DSVL') has
been recompiled with VS 2010 SP1. There should no longer be any need to include
msvsr71.dll or msvcp71.dll with ARToolKit-based applications, and these files
have been removed from the installed version of ARToolKit.
Bug fixes:
- The tool for generating NFT datasets, genTexData, now enforces a lower limit
of 196 pixels square on the smallest image in the image set. This corrects an
error which occured during KPM data creation when small images were used.
- A bug in eliminating marker matches with low confidence values when using
mixed pattern/barcode detection mode has been corrected.
- iOS examples: Removed an extraneous -drawView call from EAGLView's
-layoutSubviews method.
- genTexData now allows generation of a dataset with a single resolution
(provide the same value for min and max DPI).
- Include API reference for ARWrapper in release package.
- Ensure all glStateCache(En/Dis)AbleTex2D calls are proceeded by
glStateCacheActiveTexture() and all
glStateCache(Dis/En)ableClientStateTexCoordArray calls are proceeded by
- Don't require ARParam to be kept around for lifetime of
Changes in version 5.0.4 (2013-10-17).
New features:
- This release includes libARWrapper (previously known as libARToolKitWrapper)
which was previously supplied only with ARToolKit for Android. As ARWrapper has
utility as a generic simplified C API to ARToolKit (for example when binding to
Java or C#) it will now be provided for all platforms.
- Full source code for the NFT utilities is now provided. This will allow
customisation of the NFT dataset generation.
Bug fixes:
- mtxRotatef()/mtxRotated() (included in <AR/gsub_mtx.h>) now correctly
normalise a non-normal axis of rotation. Previously, rotations were incorrect if
the axis was not normalised.
Changes in version 5.0.3 (2013-10-07).
- This release adds support for the iPhone 5s and 5c.
Changes in version 5.0.2 (2013-10-04).
Bug fixes:
- The glm model loader for Wavefront .obj files now better handles non-standard
.obj files. Additionally, an option has been provided to flip textures on .obj
files in the vertical dimension, as many .obj models are written with textures
flipped. To enable texture flipping for a single .obj model, add this line to
the model definition in the models.dat file: "CONFIG TEXTURE_FLIPV" (without the
- iOS: Fixed a problem building EAGLView on the pre-iOS 7 SDK (added inclusion
of QuartzCore headers). 
- iOS: Fixed a problem in ARViewController which lead to the ARView not being
released when the view controller was disposed of.
- This release updates the included OpenCV libraries to version (on
Windows, OS X, and Linux).
Changes in version 5.0.1 (2013-09-18).
Bug fixes:
- A bug in handling of frame-sequential stereo has been corrected. Note that
frame-sequential stereo generally requires a fixed frame rate, which is not
guaranteed by GLUT. Platform-specific window-handling code will be added in a
future release.
- NFT input images are required to have an even number of pixels in both width
and height. A check has been added to genTexData to enforce this.
- Handling of file extensions in readtex() (used on iOS and Android) is now
- A bug in ARHandle initialisation which affected Windows debug builds has been
Changes in version 5.0 (2013-09-06).
New features:
- New format for the NFT datasets (.iset, .fset and .fset2). API is
substantially similar, with a few necessary changes documented at
Upgrading_to_ARToolKit_v5.0 . You will need to regenerate your datasets using
- OpenGL ES 2.0 support. A new library libARgsub_es2 provides the essential
connection between ARToolKit and OpenGL ES 2.0, and includes code to manage
shader programs, and also matrix math analogues of the OpenGL fixed-function
matrix utilities. The matrix library is useful elsewhere and so has also been
added to libARgsub_es and libARgsub_lite. On iOS, the EAGLView class has been
enhanced to allow runtime selection of either an ES2 or ES1 context.
- The native video formats on Android (NV21) and iOS (420f) are now handled
natively in ARToolKit, resulting in substantial performance improvements both in
video handling and tracking on these platforms.
- ar2VideoGetImage() and arglDispImage() now support retrieving and rendering
bi-planar format images from the camera. Performance is best with libARgsub_es2,
but even libARgsub_es's performance with these formats is better than that of
rendering BGRA format images due to some hand-optimised ARM NEON code.
- The iOS video module (videoiPhone) now allows requesting of different pixel
formats at runtime via a video configuration string option. See
- The ARMarkerSquare class used on iOS and native Android now automatically
supports specification of square barcode markers in the markers.dat file.
- Android (Java): Matching confidence and confidence cutoff may be queried.
- Greatly improved support for different stereo display types in the stereo
examples (stereo and stereoOptical) and calib_optical. Use the --help
command-line option to see the control parameters.
- Many more of the examples now use the ARMarker* classes, which offer a simple
standard way to specify markers via a file (markers.dat by default), including
(on desktop): simpleOSG, nftSimple, nftBook, stereo, optical, and stereoOptical,
all apps on iOS except ARAppES1 and ARApp, and on Android all the fully-native
- Several more apps now support model loading and rendering via OpenSceneGraph,
through the VirtualEnvironment class or C-pseudoclass.
- Command-line options have been improved amongst the utilities. Use '-h' or
'--help' after any utility name to see a full listing of its command-line
- Optical see-through calibration has been improved, with better on-screen help,
and with support for calibrating stereo optical displays against a single
- On Android, the Eclipse project files have been improved with the addition of
C project files for the mixed-native and native examples. The CDT Eclipse plugin
is required. See
- When using template matching (square picture-based markers) with mono or
biplanar video formats, mono matching will be selected by default. Conversely
colour matching will be used for colour formats.
- iOS: When using the front camera, the image will be mirrored by default. This
is achieved by new flipping support in ARView and argl. Previously, this
flipping was achieved by mirroring the incoming video, but this caused other
problems (e.g. NFT wouldn't track correctly). Now, tracking occurs correctly,
and the effects on lighting of OSG models are also offset by support in libARosg
(via VEObjectOSG class) for reversing the polygon winding when mirroring the
video rendered scene. See example usage in ARViewController and ARView.
Bug fixes:
- Saving of optical parameters from calib_optical had been broken in a release
in the 4.6 series, and this has been fixed. Optical calibrations will need to be
recalibrated. Additionally, the optical parameter matrix stored on disk is now
the position of the camera relative to the observer's eye, rather than the
reverse. This makes use of optical parameters in rendering a single matrix
multiplication. See optical/stereoOptical for new example usage.
- Linux: The configure script now offers an option to avoid trying to build
ARToolworks-internal-only code (i.e. libARICP and the NFT code).
- Hundreds of other minor bug fixes.
- iOS: Camera parameters for 16:9 video formats will now be more reliably drawn
from 16:9 calibrations.
- Android native apps will 'fill parent'. For the other apps using the camera
preview, it's more complicated… a solution will be provided in a later release.
- An issue on OS X when 2 USB cameras can't both be served simultaneously should
now result in a graceful failure with a timeout error message rather than a hang
inside libARvideo.
Other changes:
- For performance, an optimised form of the calibrated camera parameters
(ARCparamLT) is now used internally by ARToolKit. See the examples for usage,
and the upgrade guide for API changes. Camera parameters format on disk is
identical, although it is also possible to save and load the optimised form on
- iOS/Android: The OpenGL ES state cache (glStateCache) implemented by ARToolKit
has been updated. If you are using OpenGL commands in your app, it is advisable
to examine the list of functions whose state is handled in the cache, so that
you are able to switch your usage to the cache and achieve correct and optimal
rendering. Multitexturing support has been added to the ES1 cache.
- The optical see-through example is now named "optical" rather than
simpleLiteOptical. The new stereo optical example is named stereoOptical.
- Android: ARNativeExample is now named just ARNative.
- Android: native apps using ARToolKitWrapper don't need to link against
libjpeg, since it's now linked into the wrapper itself.
- iOS: Objective C private instance variables in classes such as
ARViewController, ARView and VirtualEnvironment are now listed in the
@implementation block, consistent with modern Objective C runtime style.
- Marker pose filtering is now available to all examples using the ARMarker*
classes. The simpleOSGFilter desktop example has been removed.
- Continuous pose estimation, which was previously used by default has now been
made a user-enabled option (i.e. it is off by default). This will result in
increased "jitter" of marker poses, but should alleviate the problem where badly
calibrated cameras would produce bizzare "inverted" poses. It is still
recommended to use good camera calibration data, and re-enabled continuous pose
estimation in your code.
Changes in version 4.6.9 (2013-04-09).
New features:
- ARToolKit for Android: Added a user-visible camera preferences screen to the
examples. The preferences screen is automatically added to any applications
based on ARBaseLib's ARActivity class. See
ARToolKit_for_Android_Camera_Preferences for more information.
Bug fixes:
- Fixed an initialisation error introduced in 4.6.6 which affected
auto-thresholding modes (not enabled by default).
- Android ARMovie example: fixed issue with playback not resuming when activity
is paused and resumed.
Changes in version 4.6.8 (2013-03-27).
New features:
- ARToolKit for Android now includes an example of playback of a video file on a
marker surface. The example is NDK (native)-based and is named ARMovie. Movie
playback is only supported by Android OS v4.0 ("Ice Cream Sandwich") and later
(Android API level 14), and support varies in quality and reliability from
device to device. It is highly recommended that you provide alternate playback
mechanisms for devices where playback in the AR environment cannot proceed, e.g.
full screen playback.
- On iOS and Android examples which load markers from a configuration file (iOS:
ARApp2, ARAppMovie, ARAppOSG; Android: ARNativeOSG), the tracking will now
automatically be set to match the types of square markers (template (pictorial)
vs. matrix (barcode)) used in the configuration file. It is not recommended that
template and matrix markers are mixed in the same application, as this lowers
the tracking reliability of both types.
Bug fixes:
- Android: A reliable fix has been found for the long-standing issue on some
devices where after an app is exited and relaunched, the camera preview surface
appears above the augmented surface. The fix adds a call to
GLSurfaceView.setZOrderMediaOverlay(true), and then adds the camera preview to
the window before the GLSurfaceView. Java-based apps will automatically inherit
the fix (via ARBaseLib). Code based on the native examples should be updated
with the updated method in the example's Activity.onStart() method.
- Android: Improvements to the startup and shutdown of the example Activity
classes mean that the previous requirement for the ARActivity to have
noHistory:true set in its manifest has been removed.
- Android: The DEBUG preprocessor macro is now defined in the native code
modules when building in debug mode. (Previously, only NDEBUG was available, for
release mode builds).
Changes in version 4.6.7 (2013-03-05).
- Extra functionality for handling OSG objects with animations has been added to
Bug fixes:
- Android: fixed a bug introduced in 4.6.6 which affected optimised code running
on devices with an ARMv7 CPU without NEON (including Nvidia Tegra 2-based
- Fixed a rendering bug in EdenSurfacesDraw (added in 4.6.6).
Changes in version 4.6.6 (2013-02-11).
New features:
- A new Android native example demonstrated loading of square markers and
rendereing with OSG.
- Portions of the utility library libEden's "Surfaces" interface for texture
handling has been reworked. A new function EdenSurfacesDraw provides a
convenient method for drawing a texture in an OpenGL scene.
- For the iOS NFT examples, loading/unloading of the .fset data has been moved
into the ARMarkerNFT class. For the purposes of page numbering, a weak reference
to the data is still held in the ARViewController class. With this change, it is
now possible to get the width and height of an NFT surface by querying
marker_width and marker_height. Previously this was possible only for square
- iOS/Android (ARM) improved performance of image processing for
auto-thresholding and NFT. For native Android applications, the Android
"cpufeatures" static library must be linked along with ARToolKit's native
- iOS: Improvements to -capturePhoto method and enabled options for optimised
flipping/rotating of incoming video. Also enabled "photo", cif (352x288) and
1080p (1920x1080) video resolutions.
Changes in version 4.6.5 (2013-01-14).
New features:
- In the OSG-based examples on the desktop platforms (simpleOSG and
simpleOSGFilter) support is now included for loading common image formats as
models. Additionally, a transparency hint can be supplied. This allows for (for
example) transparent .png files to be displayed on markers. An example file has
been included in these examples, displaying the ARToolworks logo on the
"sample2" pattern.
Changes in version 4.6.4 (2012-12-21).
New features:
- Android: Asset handling on Android has been overhauled. Previously, assets
required by the native code were unpacked in the Activity's onCreate() method to
a folder named "AR" in the external storage, resulting in wasted launch time,
unreclaimed storage space if the app was uninstalled, and potentially, asset
conflicts. Now, assets are unpacked in an Application subclass to the
application's cache on the internal storage. On subsequent launches, the assets
are used from cache, saving time. Also, if space on the device is short, Android
can clear this cache automatically, or the user manually. Finally, if the app is
uninstalled, this space is reclaimed. One rule needs to be observed: if the
application's assets are changed, the "VersionCode" field (an integer) in the
application's AndroidManifest.xml MUST be changed (usually incremented).
- iOS: In iOS video module, added tokens for iPad (4th generation) and iPad
mini. Also, renamed iPad (March 2012) to iPad (3rd generation). Both new iPads
use the same camera calibration as the iPad 3.
- iOS: In CameraVideo, added "flipH" property, and "-capturePhoto" method.
- Android: Transfer of video frames from Java to native now always uses
JNI_ABORT in the operation. Previously, this behaviour was seen by default on
some devices, while others were engaging in expensive reverse copies (causing a
lot of garbage collector activity). This is a performance enhancement.
Bug fixes:
- iOS: Corrected an issue under iOS 6 where the ARViewController was getting
unwanted autorotations as the device was rotated. See
Updating_an_AR_application_with_the_latest_ARToolKit_for_iOS_example_code for
more info.
- Added an ARLOGperror() macro and used it where required. This should improve
debug output on Android.
- iOS: The obsolete "screenshot" method has been removed from ARViewController.
The recommended means of taking a snapshot of the ARView is -snapshot and
related methods in ARApp's ARViewController.m.
Other changes:
- Android: Changed's initialiseNative method to expect path to
resources directory, and changed to supply the cache directory
as working directory. Updated Java-based examples to match. However, the native
(NDK-based) examples will infer the path to the cache directory based on the
package name. This will be improved in a later release.
- iOS: In the NFT examples, trackingSub has been made identical to the version
on the desktop-OS examples.
Changes in version 4.6.3 (2012-12-06).
New features:
- The OpenSceneGraph (OSG) model loader and renderer is now supported in
ARToolKit for Android. At present, support is limited to NDK-based applications.
A new Android example nftBook provides a full demonstration of OSG rendering.
The file shows how to link correctly. Note that prior to linking, the
OSG libraries are extremely large, but will shrink considerably after symbol and
dead code stripping during linking. OSG version 3.1.4 is supplied.
- Android: Updated to build with Android NDK r8c, and added support for x86 and
mips architectures. Updated to OpenCV 2.4.3. These changes require dropping
support for Android 2.1 (API level 7). Android 2.2 (API level 8) is now the
minimum supported version.
- Video encoded with an alpha channel is now supported by the QuickTime video
input module. (Available on 32-bit Windows and Mac OS X only, can be selected by
using "-device=QUICKTIME" for video config.) The calling application must
enabled blending on the OpenGL texture for video with an alpha channel to render
correctly. (Typically: glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
Bug fixes:
- A bug in mk_patt which prevented pattern-based square markers with
non-standard border sizes being correctly saved has been fixed. Markers
generated with non-standard border sizes should be regenerated.
- A correction to a macro in video2.c now allows the new VideoImage module to
open correctly on non-Mac OS X platforms.
Other changes:
- The Android ARNativeNFT example has been renamed to nftSimple, for consistency
with other supported ARToolKit platforms.
Changes in version 4.6.2 (2012-10-29).
- A new video input module "VideoImage" allows input from one or more JPEG
images. This module is enabled by default on Windows, Linux and Mac OS X, and
can also be enabled on iOS with a single change to include/AR/config.h.
- iOS: Add a notification and properties to ARView for touch events.
- iOS: In ARAppOSG's VEObjectOSG, listen for touches and correctly work out when
they intersect the models.
Bug fixes:
- Fixed a serious issue with filtering. On all platforms using the ARMarker
structure or class, filters were not being automatically reset after loss of
tracking, resulting in some circumstances in the filtered position placing the
object well outside the field of view. This bug fix should solve one source of
the "disappearing object" bug in ARToolKit for Unity.
- Created a user-editable constant "PAGES_MAX" for the NFT examples (nftSimple &
nftBook on Mac OS X, Windows and Linux; ARAppNFT & ARAppNFTOSG on iOS,
ARNativeNFT on Android) which sets the maximum number of NFT pages that may be
specified in the markers.dat file.
- iOS: Corrected a bug in ARView in touch-coord projection when the OpenGL
content was drawn rotated with the device.
- iOS: Fixed bug where some of the iPhone .nib files were missing the
"fullscreen" property on their UIWindow instances, resulting in loss of touch
events along the bottom of the screen.
- iOS: Added clearing of stencil buffer (when present, which by default was
never), in ARView.
Changes in version 4.6.1 (2012-10-03).
- Support for iPhone 5 and iPod touch 5th Generation screen size and cameras.
- Support for Apple's iOS 6 has been added. Support for iOS 6.0 requires use of
Xcode 4.5, and this has a number of consequences; binaries are now built as
armv7 + armv7s. armv6 is no longer supported, meaning that the minimum
deployment target is now iOS 4.3, and the iPhone 3G can no longer be supported
(the oldest supported model is now the iPhone 3GS). The project files have been
updated to reflect this change. Users who still wish to support iPhone 3G can
continue to use ARToolKit for iOS 4.6.0 (release 11) with Xcode 4.4.x.'
- The bundled OpenSceneGraph libraries have been updated to v3.1.3 on iOS.
Bug fixes:
- A problem with texture loading when using Wavefront .obj models in the Android
examples has been fixed. Now, a new function glmReadOBJ2 delays loading and
submission of the textures until the model is ready to be drawn. Previously,
texture loading was performed when the model was loaded, and typically no OpenGL
context would be valid at that point.
- On Android, debug output now goes to the Android logging facility, meaning
that debug output from native ARToolKit should now be visible in Logcat (with
the log tag "libar").
- calib_camera now accepts file names with spaces when saving the calibrated
- Extraneous header inclusions removed from simpleMovie.c.
Changes in version 4.6.0 (2012-08-31).
New features:
- NFT tracking is now included in all ARToolKit releases on all platforms.
- Two new examples NFT-based for the desktop platforms: nftSimple, and nftBook.
These display simple and advanced rendering on NFT surfaces. The formats used in
the markers.dat and objects.dat file match those found in the ARToolKit for iOS
and Android NFT examples.
- NFT dataset creation utilities with the same improved ease of use and
functionality as found on the mobile platforms are now provided for the desktop
platforms. This means NFT datasets can be shared seamlessly between applications
on mobile and desktop. The genTexData utility replaces the genImageSet,
genFeatureMap, genFeatureSet and makeKpmTemplate utilities. The dispFeatureSet
replaces the dispFeatureMap and checkKpmTemplate utilities.
- The checkid utility has had some minor improvements in command-line handling
and the types of information displayed. Please see its help page.
- If opening movie files as video streams (via the QuickTime video module on Mac
OS X or Windows), note that only URLs are now accepted. To construct a "file://"
URI for a local file, a new convenience function arUtilGetFileURI has been added
to libAR. The simpleMovie example shows the new simplified usage.
- Pixel format information is now handled more consistently throughout the SDK,
with AR_PIXEL_FORMAT used everywhere and AR_PIXEL_FORMAT_INVALID used to signal
an invalid or unhandled format.
- The calib_camera, calib_stereo and check_id applications have been improved
and enhanced with better handling of command-line options. Run these utilities
with the -h or --help option to see a summary of available options.
- The winDF video module for interfacing with the Point Grey FlyCapture SDK
(Windows-only) has been enhanced with some runtime configurable options. See
- The OSG-based projects now build for 32- and 64-bit on Mac OS X, provided OSG
v3.1.3 or later is used. See for
an installer for OSG for Mac OS X.
- A full OSG release is now bundled with ARToolKit for Windows.
Bug fixes:
- When using calib_camera or calib_stereo, camera frame sizes bigger than the
screen were being cropped. This has been corrected by retaining the full frame
tracking but scaling the drawn frame onscreen.
- A buffer overrun error in arUtilGetFileURI has been fixed.
Other changes:
- For examples using gsub_lite, initialisation via arglSetup has changed. Now,
an ARParam structure (holding the camera parameters) and pixel format are passed
in instead of an ARHandle. If debug display mode functionality is required (for
non-NFT tracking), this is now initialised separately in a new call.
  For example, in your non-NFT applications, change:
      gArglSettings = arglSetupForCurrentContext(gARHandle);
      gArglSettings = arglSetupForCurrentContext(&(gCparamLT->param),
      arglSetupDebugMode(gArglSettings, gARHandle);
  See main() in simpleLite.c for example usage.
- Support for Microsoft Visual Studio 2008 SP1 has been dropped.
Changes in version 4.5.11 (2012-07-18).
- Handling of pre-supplied iOS camera calibration data has been improved. More
information can be found in the iOS release notes.
- The artoolkit-setenv script (which sets the ARTOOLKIT_4_ROOT environment
variable on Mac OS X and Linux) should now function correctly on Mac OS X again.
- Add Android-compatibility to arUtilChangeToResourcesDirectory(). The current
"best" Android behaviour is to change to the root of the external storage
(typically /mnt/sdcard or /sdcard (pre-Android OS 3.0)).
Bug fixes:
- The default filter cutoff (5 Hz) was a bit too low. The default is now 15Hz.
This can of course be changed by the user.
- Fixed a packaging error on Windows installers that left out some files
required by the simpleOSG and simpleOSGFilter examples.
Changes in version 4.5.10 (2012-07-04).
- Improved the Windows configure script.
Changes in version 4.5.9 (2012-04-17).
Bug fixes:
- iOS: Fixed bug introduced in version 4.5.8 whereby incorrect tear-down of the
camera connection could under some circumstances lead to a crash. 
- iOS: Corrected Objective C object disposal in case of initialisation failure
in VirtualEnvironment and VEObject* classes.
Other changes:
- iOS/Android: Changed marker handling to search for maximum of 30 markers per
frame, and maximum of 25 picture (template) markers. (Limits on other platforms
are 60 and 50 respectively.)
- Android: the ARSimpleBarcode example has been renamed ARNativeBarcode, to
better reflect its structure.
- iOS: Users of the MovieVideo class can now listen for the NSNotification
MovieVideoPlayBackEndedNotification to be notified of the end of playback of a
movie file.
- iOS: Improved handling of errors during movie loading in MovieVideo and
VEObjectMovie classes.
- iOS: Added correct compile-time flag for disabling Thumb code-generation when
using LLVM compiler.
Changes in version 4.5.8 (2012-03-28).
- Added support for the iPad (March 2012) to the iOS release. Also improved
support for future iOS-based devices.
Bug fixes:
- Fixed bug in an OSG header encountered when using Xcode 4.3.x.
Other changes:
- Modification in behaviour of arPattLoadFromBuffer to allow use of const string
Changes in version 4.5.7 (2012-02-14).
- Added arUtilChangeToResourcesDirectory function to allow one-line control of
application resource path search behaviour.
Bug fixes:
- Mac OS X: Fixes for calling into the QuickTime7 video module from
non-Objective C applications.
Other changes:
- Support for Microsoft Visual Studio 2005 SP1 (vs80sp1) has been dropped.
- SGI Irix has not been supported for some time, and has now been dropped.
Changes in version 4.5.6 (2011-10-18).
- iOS: The iPhone 4S is now supported; a full set of camera calibration files is
Bug fixes:
- iOS: Some memory leaks in marker and object file loading have been fixed.
Changes in version 4.5.5 (2011-08-09).
- Extended controls and modes for ARvideo 1394dc.
- Provides support for ARToolKit NFT v3.50.0.
- Added matrix scaling functions to EdenMath.
- arOSG now supports the concept of a "local transform". This is applied after
the object's normal pose transform. Typically the pose transform is used to set
the modelview matrix for the object, so the local transform allows translation,
rotation, scaling or any combination
Bug fixes:
- Changed default threshold mode back to MANUAL. Auto modes have proven
unreliable and will be improved in a future release.
Changes in version 4.5.4 (2011-05-30).
- Extended controls and modes for ARvideo 1394dc.
- Provides support for ARToolKit NFT v3.50.0.
Changes in version 4.5.3 (2011-05-05).
New features:
- An online 2D barcode marker generator is available now at
- The 4x4 barcode marker set, and two new error-checking and correction codes
can now be selected at runtime.
- check_id now has command-line switches to control parameters of the markers
being used.
Bug fixes:
- A bug that prevented use of variable-border size markers has been fixed.
Changes in version 4.5.2 (2011-04-20).
- arOSG now allows lighting to be turned on or off per model in the model .dat
files. Also, it now allows for setting of viewpoints with the origin left or
below (0,0).
- A programmatic interface to the QuickTime movie interface is now exposed as
<AR/sys/videoQuickTimeMovie.h>. The QuickTime "movie" object can be retrieved
via a new function call ar2VideoGetMovieQuickTime().
- A number of iOS-specific code improvements are documented in the iOS release
Bug fixes:
- ar2VideoGetParams now correctly accepts a pointer to a string for the returned
string parameter.
- arOSG now turns off all ambient lighting.
- The examples now create a window the same size as the incoming camera frame.
Previously, a hard-coded window size was used.
- A number of iOS-specific bug fixes are documented in the iOS release notes. 
Changes in version 4.5.1 (2011-03-18).
- The arOSG library has added support for intersection queries, plus
enabling/disabling lighting. Also, much more state information can now be
Bug fixes:
- Mac OS X: An error which occured when closing the video stream has been
- Mac OS X: The QuickTime7 video module will now default to supplying 32-bit
BGRA pixels on Intel architectures and 32-bit ARGB pixels on ppc architectures.
This can be overridden (e.g. to supply 2vuy or yuvs-format pixels) using the
video config string.
Changes in version 4.5.0 (2011-01-24).
New features:
- arFilterTransMat functions to provide pose-estimate filtering.
- Support for Microsoft Visual Studio 2010.
- mk_patt can now train markers with non-standard border widths. The command
line switch "-border=n" (n between 0 and 0.5 (not inclusive)) specifies the
desired border width as a proportion of the marker width. The portion of the
marker which will be used as the pattern is now indicated by mk_patt by
outlining in blue. Note that in order to use markers with non-standard border
widths, the border width must be specified in the application by using the
arSetBorderSize() function (see reference documentation for more information.)
Changes in version 4.5.0d3 (2011-01-06).
New features:
- New QuickTime7 video input module for Mac, using the new QTKit Capture APIs.
It is now the default video input module on the Mac. This new module offers a
dramatic improvement in capture speed from high-definition video sources. If
desired, ARToolKit can now be built with Mac OS X 10.6 the minimum version
- New example simpleMovie, demonstrating use of the QuickTime video input module
to show a video file on a marker.
- New utility, check_id, which allows low-level debugging of multi-marker
tracking, particularly barcode marker tracking. See
for a tutorial.
Other changes:
- Support for Microsoft Visual Studio .NET 2003, and OpenVRML 0.14.3 have been
Changes in version 4.5.0d2 (2010-11-22).
New features:
- Variable marker border width. See documentation for
- Error detection and correction codes with 3x3 matrix markers. Two modes are
available, one using parity, and allowing for detection of single-bit errors
with up to 32 markers, and one using a Hamming (6,3) code, allowing for
detection of up to 3 bit errors and correction of up to 2 bit errors with up to
8 markers. Marker patterns for these modes can be found in the doc/patterns
- For identified square regions, which ultimately are not judged by ARToolKit to
be known patterns, support is now included for discovering which stage of marker
matching cutoff occured. See the documentation for the cutoffPhase member of the
ARMarkerInfo structure.
- On Mac OS X, adaptive thresholding makes use of the Accelerate framework for
improved performance.
Changes in version 4.5.0d1 (2010-10-05).
New features:
- Adaptive thresholding. This algorithm adjusts the threshold intra-frame, and
thus should help ARToolKit find markers when lighting condtions are non-uniform
across a frame. Adaptive thresholding requires a fast computer, and is not
enabled by default. The processing time taken is proportional to the number of
pixels in the image; using an 800x600 image size or smaller is recommended. It
can be enabled by calling arSetLabelingThreshMode(arHandle,
AR_LABELING_THRESH_MODE_AUTO_ADAPTIVE); Manually changing the threshold will
disable adaptive thresholding. The kernel size
be changed at compile-time. Larger values will provide better thresholding but
require a faster CPU.
Changes in version 4.4.3 (2010-08-20).
New features:
- Added arVideoSaveImageJPEG() funtion, which saves video frame to a jpeg file.
- Added a new auto threshold algorithm, based on Otsu's method, and changed this
to the default method. Otsu's method typically selects a better threshold than
the median, particularly when one or more markers are close to the camera.
- Add new config token AR_ENABLE_MINIMIZE_MEMORY_FOOTPRINT. Enabled by default
on iPhone, it removes support for the debug image, and saves several hundred KB
of memory.
Bug fixes:
- Extraneous debug output from the pose estimator (ICP) now only present in
debug builds, and goes to stderr.
- Fix for small memory leak in arVideo.
Changes in version 4.4.2 (this release) (2010-03-16).
New features:
- Auto-thresholding. ARToolKit will now by default automatically adjust the
binarization threshold to the median image brightness. The brightness is
measured using a full-image histogram, which runs by default every 8 frames.
Note that if your ARToolKit application manually sets the threshold at any time
(including during initialization) the auto-thresholding will be disabled.
- New OpenSceneGraph-based rendering library, arOSG. arOSG is intended to
provide access to the modern plugin-based scene graph OpenSceneGraph, and its
attendant model formats and graphical capabilities. An example and full API
documentation is included.
- Windows binaries of ARToolKit are now supplied with win64-x64 versions of
ARICP. win32-i386 versions now also build to subfolder of lib.
- Update Windows DragonFly video module for latest FlyCapture SDK release
(changes submitted by Henry Chu).
- Reduced contrast required to identify barcode patterns (changed
AR_PATT_CONTRAST_THRESH2 in arConfig.h to 15.0). This should enhance detection
of barcode patterns.
Bug fixes:
- Fixup of handling of path separators on Win32 in utility functions to support
osgART Professional Editon v1.1.3 ARToolKit4 and ARToolKit4NFT tracker plugins.
Changes in version 4.4.1 (2009-09-15).
Bug fixes:
- Moved some symbols from libARvideo to libAR to avoid requirement to co-link.
Changes in version 4.4.0 (2009-07-16).
New features:
- Add line matching to pose estimator.
- ARG: added "flipmode" for horizontal and vertical flipping.
- Mac can also now use video1394dc.
- New version of video1394dc, with headers and source, and configuration items.
- Add draw square to ARG.
- Add video pixel format name utility function.
Bug fixes:
- AR_AREA_MAX changed from 1e5 to 1e6. Tracking will now function better with HD
images when marker is close to the camera.
- Bug fixes in video1394dc.
- Robust ppose estimator now makes better probability estimates.
- Removal of 'static' qualifiers in multi lib.
- Remove erroneous default video config in mk_patt for Windows DirectShow video.
- Syntax error fixed in arViewerCapi.cpp.
- Fix bug in videoQuickTime when UVC driver incorrectly reports frame timing.
- Correct potential error in marker detection loop in examples.
- Fix bug whereby request for a non-default pixel format was ignored by
- Change internal lib linkage in Xcode.
- Removed some debug output from ARICP library.
Changes in version 4.3.4 (2008-11-11).
- Add support for 3 packed pixel formats (RGB565, RGBA5551 and RGBA4444).
- Addition of asynchronous fetching of video frames. New function
ar2VideoGetImageAsync. At present, implemented only in dummy video.
- Support for requesting power-of-2 sized buffers (via config string
"-bufferpow2") from dummy video lib.
- Replaced all double-precision floating point declarations with a macro which
can be redefined to single-precision floating point as an optimisation.
- Add 4x3 and 8x6 multi patterns and PDFs and Letter-size multi PDF.
- Change multi-marker loading to allow backwards compatibility with config files
from ARToolKit v2.x.
Bug fixes:
- Some gstreamer fixes incorporated, including correct pre-rolling with some
additional source types, correction of default video config, and compatibility
with new gstreamer releases.
- Fixes to dual-mode marker detection (two pass detection of both matrix and
template markers). arSetPatternDetectionMode no longer incorrectly rejects
two-pass modes as invalid.
- Debug image alpha channel (where appropriate) is now set to opaque.
- More headerDoc documentation added.
Changes in version 4.3.3 (2008-02-18).
New features:
- Scripts to set and unset the ARTOOLKIT_4_ROOT environment variable have been
added for the Linux and Mac OS X platforms. See the "share" directory.
- A script "share/artoolkit5-config" allows 3rd-party applications to query
ARToolKit build settings on the Linux and Mac OS X platforms.
Bug fixes:
- ARToolKit now assumes a little-endian architecture on Linux if the
__BIG_ENDIAN__ macro is not defined by the preprocessor.
- Change in multi-marker pattern file format (arMultiReadConfigFile); pattern
filenames in a multimarker config file are now relative to the config file,
rather than the working directory.
Changes in version 4.3.2 (2008-01-20).
New features:
- A new example, multiCube, demonstrates the use of non-planar multimarker sets,
in this case a cube. Sample PDFs for cube markers are in doc/patterns/Cubes.
- Add VideoGStreamer (LGPL license) which uses the GStreamer library for video
input. Copyright Hartmut Seichter and ARToolworks, Inc.
- The environment variable ARTOOLKIT_4_CONFIG can now be used to globally set
the video configuration to be used when none is specified in the call to
Bug fixes:
- Configuration of Makefile builds (Linux, and optionally Mac OS X) has been
cleaned up.
- "-device=" option can now safely be passed to video input modules which don't
use "-option" syntax.
- gsub_lite is now correctly built in Makefile builds.
Changes in version 4.3.1 (2008-01-08).
Other changes:
- Update Xcode project for Xcode 3.0 compatibility.
- Add arVideoUtilGetPixelFormat to libARvideo (duplicate of libAR's
arUtilGetPixelFormat) to allow independent linkage.
Changes in version 4.3 (2007-10-31).
New features:
- Hirokazu Kato has rewritten his original fast pose estimator a modern
algorithm. The new pose estimator offers comparable accuraccy, with much
improved speed.
- A robust pose estimator has been added. See the documentation for functions
arGetTransMatRobust() and arGetTransMatStereoRobust(). These functions are also
available under multi-marker tracking.
- Examples for multi-marker tracking and stereo tracking added.
- Video input via QuickTime from file and streaming video sources has been added
on Mac OS X and Windows. Full documentation is available in the ARToolworks
support library.
- A set of utilities for Linux 1394dc video have been added: whitebalance,
checkimage, listcamera.
- Camera calibration is now performed using the OpenCV library and is greatly
simplified. A new version 4 of the camera calibration parameters is now saved.
Camera calibration files generated with the earlier (versions 1 through 3) of
the camera calibration utility may still be used. The old camera calibration
utility is available as calib_camera_old-v3.
- Multi-marker tracking is now available in two modes, template (pictorial
markers) and matrix (2D-barcode markers). These modes can be used exclusively or
together in a two-pass arrangement.
- Some convenience functions added to gsub library: argGetScreenSize(),
- Video parameters under the Linux 1394dc video library can now be saved and
- ARvrml, the VRML renderer, now supports openvrml-0.16.6 on all platforms, and
builds as a DLL on Windows to ease Building of programs that use ARvrml.
Bug fixes:
- arUtilSleep() now correctly operates in milliseconds on Unix-based systems.
Other changes:
- Minor changes in the parameters to some functions: please check the
documentation for more information: arGetDebugMode(), arGetLabelingMode(),
arGetLabelingThresh(), arGetImageProcMode(), arGetPattDetectionMode(),
arGetMarkerExtractionMode(), arGetTransMat(), arGetTransMatStereo(),
- The following functions have been removed: arGetTransMatSub(),
arGetTransMatSubStereo(), arModifyMatrix(), arModifyMatrixStereo(),
arGetAngle(), arGetRot(), arGetNewMatrix(), arGetInitRot().
Known issues in this release.
- The Mac video library does not yet use the new QuickTime 7 video pipeline.
- SGI video input is missing.
Changes in version 4.1.3 (2007-05-12).
- Addition of routines to load and save optical calibration sets, updated
calib_optical, and simpleLiteOptical example.
Changes in version 4.1.2 (2007-04-24).
- Addition of calib_optical tool for calibration of optical see-through
camera-display combinations.
Changes in version 4.1.1 (2007-04-03).
- Major modification to accommodate changing distortion function version at
runtime. Several function prototypes have changed.
- Lots of new headerDoc documentation in code.
- Began maintaining ChangeLog inside release archives.
Personal tools