Read me for ARToolKit-2.72. =========================== Contents. --------About this archive. The ARToolKit license model. Building on Windows.

Building on Linux / SGI Irix. Building on Mac OS X. Changes in this release. Known issues in this release. Changes in earlier releases. About this archive. ------------------This archive contains the ARToolKit libraries, utilities and examples, version 2 .72. ARToolKit version 2.72 is released under the GNU General Public License (GPL). P lease read the file COPYING.txt. The latest version of ARToolKit is available from http://sf.net/projects/artoolk it. ARToolKit is designed to build on Linux, Windows, Macintosh OS X, and SGI Irix p latforms. This archive was assembled by: Philip Lamb HIT Lab NZ http://www.hitlabnz.org 2006-11-20 The ARToolKit license model. ---------------------------ARToolKit is made available under a dual-license model. As it has been since the first public release of version 1.0, ARToolKit is freely available for non-comm ercial use under the terms of the GNU General Public License. A proprietary vers ion of ARToolKit developed in parallel for professional commercial use by ARTool works, Inc. is made available under different license terms, to suit end-user ne ed. We believe this model offers the best of both worlds. Persons developing their s oftware under an open source model are freely availed of the ARToolKit source co de, and the ARToolKit open source project benefits in return from enhancements, bug reports, and external development ideas. Those persons developing under a pr oprietary source model, from whom the ARToolKit code base does not benefit throu gh reciprocal openness, contribute financially instead. License fees fund resear ch and development of today's and tomorrow's versions of the ARToolKit through r esearch activities at partner institutions. The GPL-licensed toolkit.: ARToolKit versions 1.0 through 2.x are available under the GPL. Please read the full text of the GPL prior to downloading and/or using the ARToolKit source code

. Your downloading and/or use of the code signifies acceptance of the terms and conditions of the license. If you are unable to comply with the license terms, p lease immediately destroy all copies of the code in your possession. Please be aware that while the GPL allows you to freely use the source code, it also imposes certain restrictions on the way in which you can use the code. Your attention is drawn particularly to section 2b of the GPL: "You must cause any w ork that you distribute or publish, that in whole or in part contains or is deri ved from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.", i.e. your software inco rporating or linking to ARToolKit must also be open-source software, licensed un der the GPL. Use of the ARToolKit in breach of the terms of the GPL will be subj ect to legal action by the copyright holders. Licenses for professional and commercial use.: In response to demand from toolkit users, the holders of the copyright on much o f the ARToolKit version 1.0 - 2.x code have elected to make this code and other substantially advanced ARToolKit and AR code available under proprietary license s for professional and commercial use by persons for whom the GPL license is not ideal. These license arrangements are managed by ARToolworks, Inc., Seattle, WA , USA. A variety of license types are available at reasonable cost. Please conta ct ARToolworks, Inc. directly for information on products, license terms, and pr icing. ARToolworks also provide a variety of value-added services, including profession al support, customization and other modifications, and end-user turnkey applicat ions. Building on Windows. -------------------Prerequisites: * Microsoft Visual Studio .NET 2003 or Visual Studio 6, or a free development environment such as Cygwin. * DSVideoLib-0.0.8b-win32. Download from http://sf.net/projects/artoolkit. * GLUT. Download from http://www.xmission.com/~nate/glut/glut-3.7.6-bin.zip. * (Optional, for VRML renderer only) OpenVRML-0.16.1-bin-win32. Download from http://sf.net/projects/artoolkit. Build steps: (1) Unpack the ARToolKit zip to a convenient location. This location will be ref erred to below as {ARToolKit}. (2) Unpack the DSVideoLib zip into {ARToolKit}. Make sure that the directory is named "DSVL". (3) Copy the files DSVL.dll and DSVLd.dll from {ARToolKit}\DSVL\bin into {ARTool Kit}\bin. (4) Install GLUT, following the instructions in the README.win file inside the G LUT zip. See http://www.hitlabnz.org/forum/showpost.php?p=332&postcount=12 for m ore detail on how to install GLUT on Windows. (5) Run the script {ARToolKit}\Configure.win32.bat to create include\AR\config.h . (6) Open the ARToolKit.sln file (VS.NET) or ARToolkit.dsw file (VS6). (7) Build the toolkit. The VRML renderering library and example (libARvrml & simpleVRML) are optional b uilds: (8) Unpack the OpenVRML zip into {ARToolKit}. (9) Copy js32.dll from {ARToolKit}\OpenVRML\bin into {ARToolKit}\bin.

(10) Enable the libARvrml and simpleVRML projects in the VS configuration manage r and build. Building on Linux / SGI Irix. ----------------------------Prerequisites: * (Optional, for VRML renderer only) openvrml-0.16.1 and dependencies. Downloa d from http://sf.net/projects/openvrml. Unpack the ARToolKit to a convenient location. The root of this location will be referred to below as {ARToolKit}: tar zxvf ARToolKit-2.72.tgz Configure and build. The Linux builds support video input using either Video4Lin ux, an IIDC-compliant or DV camera connected via IEEE-1394, or a Sony EyeToy cam era connected via USB. Alternatively you can use GStreamer 0.10 (0.8 is not supp orted and also not recommended) as input method. This requires you to install th e gstreamer development packages for your Linux distribution. You will be prompt ed as to which of the four Linux video drivers you wish to use at the Configure step. cd {ARToolKit} ./Configure make Following a successful build, to run a binary such as simpleTest: cd {ARToolKit}/bin ./simpleTest The VRML renderering library and example (libARvrml & simpleVRML) are optional b uilds: cd {ARToolKit}/lib/SRC/ARvrml make cd {ARToolKit}/examples/simpleVRML make cd {ARToolKit}/bin ./simpleVRML Building on Mac OS X. --------------------------Prerequisites: * Apple's Developer Tools. http://developer.apple.com * Camera driver. Mac OS X 10.3 and later include an inbuilt IIDC and DV FireWi re camera driver. The macam project provides USB camera drivers for OS X, http:/ /webcam-osx.sf.net. * (Optional, for VRML renderer only) Apple X11. Install X11 from the Mac OS X installer, from the "Optional installs" package, or download an install disk im age from http://www.apple.com/downloads/macosx/apple/x11formacosx.html. * (Optional, for VRML renderer only) OpenVRML-0.16.16-bin-MacOSX.tar.gz. Downl oad from http://sf.net/projects/artoolkit, or alternatively install via Fink. Do wnload Fink (and optionally, FinkCommander) from http://fink.sourceforge.net/dow nload/. Building using the XCode IDE: (1) Unpack the archive to a convenient location using StuffIt Expander, and open the ARToolKit.xproj. (2) Builds include a script target "Configure" which enables accelerated and rec tangular texturing by default. If you wish to change these defaults, manually ru n the ./Configure script from Terminal as for a command-line build.

(3) Mac OS X XCode builds now build the examples as bundled applications. The co ntents of the "Data" directory are copied into the application bundle at build t ime. The applications can thus be moved from their build locations. The utilitie s are still (mostly) built as command-line tools. The VRML renderering library and example (libARvrml & simpleVRML) are optional b uilds: (4) Unpack the OpenVRML .tar.gz into the ARToolKit folder, or alternatively, if using FinkCommander, do a binary install of mozilla-dev, followed by an install of openvrml4-dev and openvrml-gl5-dev. (5) Select the ARToolKit extensions target, and build. Alternately, ARToolKit can be built from the Terminal, using the Unix makefiles. Drop the ARToolKit into a convenient location, e.g. your Desktop, then open a Te rminal window and type: cd ~/Desktop tar zxvf ARToolKit-2.72.tgz Configure and build cd ~/ARToolKit ./Configure make Following a successful build, to run a binary such as simpleTest, add these comm ands: cd bin ./simpleTest The VRML renderering library and example (libARvrml & simpleVRML) are optional b uilds: Either: tar xzvf OpenVRML-0.16.16-bin-MacOSX.tar.gz ~/Desktop/ARToolKit Or: fink -b install mozilla-dev fink install openvrml6-dev openvrml-gl6-dev Then: cd ~/Desktop/ARToolKit/lib/SRC/ARvrml make cd ~/Desktop/ARToolKit/examples/simpleVRML make cd ~/Desktop/ARToolKit/bin ./simpleVRML Changes in version 2.72 (this release) (2006-11-20). -----------------------------------------------------All platforms: - New feature: ARToolKit now supports querying of SDK and runtime versions. - New feature: There are now right-hand coordinate system versions of the OpenGL projection and modelview matrix functions, named arglCameraFrustumRH and arglCa meraViewRH, respectively. These will help when integrating ARToolKit into existi ng OpenGL drawing. - Enhancement: Support for AR_PIXEL_FORMAT_MONO is now included. - Enhancement: gsub_lite now supports arDebug mode. - Enhancement: ARvrml now builds against OpenVRML-0.16.1. - Enhancement: The license model is now stated more clearly in the readme. Mac OS X: - Bug fix: Fix for an error in the VRML library inclusion on Mac OS X. - Bug fix: Now detects if running emulated on Intel Macs, and optimises video fo r this case. - Enhancement: Two new video config tokens are now available; -fliph and -flipv,

which will mirror the video image horizontally and vertically respectively. Linux: - New feature: Support for gstreamer video capture added, thanks to Hartmut Seic hter. - Enhancement: Major changes to Video1394DC- add PointGray DragonFly support, ad d LGPL/GPL license info, better config string support, stabilised interfaces, lo ts of clean ups to make the code easier to work with. - Bug fix: Using PAL in VideoLinuxDV as reported at http://www.hitlabnz.org/foru m/showthread.php?t=412. Known issues in this release. ----------------------------- On Windows, it is not easy to work out what to put into the DSVideoLib xml con fig file. Particularly, DirectShow IDs may include a "&" character, which needs to be escaped in xml (i.e. changed to "&" wherever it occurs). - The Mac video library does not yet use the new QuickTime 7 video pipeline. - Changing the pixel format requires recompilation of libAR. This problem is sol ved in ARToolKit Professional v4 (commercially-licensed). - The Mac default pixel format has been changed back to ARGB for compatibility w ith the OSGART project release. Changes in earlier releases. ---------------------------Please see the file ChangeLog.txt. -EOF