ARToolKit Professional for Android release notes

From ARToolworks support library

Jump to: navigation, search

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

Latest release: 12.



Supplementary read me for ARToolKit Professional for Android, release 12.
About this archive.
Getting started.
Next steps.
Release notes.
About this archive.
This archive contains the ARToolKit Professional library and examples for
Android, release 12.
ARToolKit Professional for Android 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.
This archive was assembled by:
    Philip Lamb
    ARToolworks, Inc.
 * Android SDK Tools r12 (for Android 2.2/API 8) or later required, r20 (July
2012) or later recommended.
 * Development of native ARToolKit for Android applications or requires Android
NDK Revision 5 or later, revision 8c (Nov 2012) recommended.
 * Use of the Eclipse IDE is recommended, and Eclipse project files are supplied
with the ARToolKit for Android SDK.
 * An Android device, running Android 2.2 or later. Testing is not possible
using the Android Virtual Device system.
 * A printer to print the pattern PDF images.
ARToolKit Professional for Android 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 Android release alongside a regular full release of ARToolKit
Professional v4.x for Mac OS X, Windows, or Linux.
Getting started.
For full instructions on using this SDK, please refer to the online user guide
Next steps.
We have made a forum for discussion of AR for Android 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.
Release notes.
Changes in release 12 (2013-04-09):
Updated underlying ARToolKit to 4.6.9. A summary of Android-relevant changes
since release 11:
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 release 11 (2013-03-27):
Updated underlying ARToolKit to 4.6.8. A summary of Android-relevant changes
since release 10:
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 release 10 (2013-03-05):
Updated underlying ARToolKit to 4.6.7. A summary of Android-relevant changes
since release 9:
- 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 release 9 (2013-02-11):
Updated underlying ARToolKit to 4.6.6. A summary of Android-relevant changes
since release 8:
New features:
- A new Android native example demonstrated loading of square markers and
rendering 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.
- 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
Changes in release 8 (2013-01-17):
Updated underlying ARToolKit to 4.6.5. A summary of Android-relevant changes
since release 7:
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).
- 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:
- Added an ARLOGperror() macro and used it where required. This should improve
debug output on Android.
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.
Changes in release 7 (2012-12-06):
Updated underlying ARToolKit to 4.6.3. A summary of Android-relevant changes
since release 6:
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.
 - 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.
  - 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 checkid utility has had some minor improvements in command-line handling
and the types of information displayed. Please see its help page.
  - 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.
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
 - Created a user-editable constant "PAGES_MAX" for the NFT examples (nftSimple
& nftBook on Mac OS X, Windows, Linux and Android; ARAppNFT & ARAppNFTOSG on
iOS) which sets the maximum number of NFT pages that may be specified in the
markers.dat file.
 - 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.
 - 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.
Changes in release 6 (2012-07-20):
New features:
- ARToolKit NFT is now included in the SDK. At present, the required libraries
are supplied, NFT support is included in ARToolKitWrapper, and a single (native)
example ARNativeNFT provides a starting point for application development. The
examples uses the "Pinball.jpg" image supplied in the "Misc/patterns" folder.
ARToolKit NFT requires a fast device, preferably dual-core for good operation,
e.g. Samsung Galaxy SII or similar. Build/deployment for Android API 9 (Android
OS v2.3) or later is recommended.
- The tools required for creation of new markers (both pattern-based and NFT) on
Windows and Mac OS X are now supplied in the ARToolKit/bin folder. See the
ARToolKit support library ( for more
information on the use of these tools.
- All the supplied examples now use the ARToolworks-supplied AssetHelper class
to copy the contents of the "assets" folder into a folder named "AR" on the
device's storage (previously "/sdcard"). There is no longer any need for the
user to do this before running the example apps.
- The examples ARSimple, ARSimpleInteraction, ARSimpleNative and
ARSimpleNativeCars retain backwards compatibility to Android API 7 (Android OS
2.1) and the examples ARNative, ARNativeBarcode and ARNativeNFT to Android API 8
(Android OS 2.2). All apps have been tested against target API 16 (Android OS
4.1) and have this API level as the default target.
Bug fixes:
- Non-fatal exceptions in AssetHelper when running on Android OS 4.x have been
- A race condition which sometimes lead to LogCat messages "call to OpenGL ES
API with no current context (logged once per thread)" has been fixed.
- Fixed an issue in the native example apps where on exiting an app (e.g. by
pressing the home button) and returning to it results in the camera preview
surface appearing in front of the OpenGL drawing. Note the new sequence of calls
in onCreate and onStart in the example activity.
- Fixed a bug encountered with Android OS 4.x where the apps would fail to
display anything when launched in portrait mode. It is recommended that all
existing apps have "<application
android:configChanges="keyboardHidden|orientation|screenSize"> added to their
manifest and are built against API level 14 or later (Android 4.0 or later).
- Updated underlying ARToolKit to 4.5.11, including the following relevant to
the ARToolKit for Android SDK:
  - 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)).
Changes in release 5 (2012-04-17).
- Updated underlying ARToolKit to 4.5.9, including the following:
  - 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.
Changes in release 4 (2012-03-09).
- Fixed significant rendering bug affecting some devices (caused by
misspecification of OpenGL clipping planes).
- Updated core ARToolKit version to 4.5.7.
- Correct handling of non-RGBA pixel formats in ARToolKitWrapper.
- Builds non-thumb code for all ARM ABIs now, which should result in significant
performance improvements on pre-ARMv7 CPU types.
- Numerous improvements to build system for Android NDK.
Changes in release 1.3 (2011-11-12).
- Following further testing of features, removal of beta status.
Changes in beta release 1.2 (2011-07-07).
- Updated core ARToolKit version to 4.5.4
- Additional examples including barcode tracking
- Initial code to unpack assets from APK
- Camera capture performance enhancements
Changes in beta release 1.1 (2011-04-20).
- Source code release based on ARToolKit 4.5.1
- NDK build scripts for building ARToolKit, ARToolKitWrapper, and examples
- User guide
Changes in beta release 1 (2011-03-21).
- Initial binary only release
- ARBaseLib Java library
- Two simple examples
Personal tools