NyARToolkit/trunk/readme.ja.txt

======================================================================
NyARToolkit
 version 4.1.1
======================================================================

Copyright (C)2008-2012 Ryo Iizuka

http://nyatla.jp/nyartoolkit/
airmail(at)ebony.plala.or.jp
wm(at)nyatla.jp

----------------------------------------------------------------------
 About NyARToolkit
----------------------------------------------------------------------
 * NyARToolkitは、ARToolKit 2.72.1を基盤としたARアプリケーション向けの
   クラスライブラリです。
 * J2SE5.0以上に対応しています。
 * ARToolKitの基本機能と、NyARToolKitオリジナルの拡張機能、フレームワーク
   で構成しています。
 * ライブラリは3部構成です。環境依存の少ないlibモジュール、環境依存性のある
   utilsモジュール、アプリケーションサンプルを実装したsampleモジュールです。
 * libモジュールは、J2MEのAPIのみで動作します。
 * utilsモジュールは、カメラ制御、3Dシステム制御等、外部モジュール毎に
   接続の為のヘルパークラスを提供します。
 * sampleモジュールは、最低限の機能を持つ、ARアプリケーション集です。


 ARToolKitについては、下記のURLをご覧ください。
 http://www.hitl.washington.edu/artoolkit/


----------------------------------------------------------------------
NyARToolkitの特徴
----------------------------------------------------------------------
NyARToolkitの特徴を紹介します。

 * 多くの入力画像を使用できます。(BufferedImage,JMF出力,バイナリ入力,他)
 * ARToolkitと比較して再利用性が向上しています。
 * 次の項目について、高速な機能が利用できます。(ラべリング、姿勢最適化、
   画像処理、行列計算、方程式計算)トータルで2倍程度の処理速度があります。
 * NyId規格のIDマーカが使用できます。
 * 複数のAR/NyIdマーカを容易に利用する為のMarkerSystemクラスがあります。
 * OpenGL向けの簡易なスケッチシステムがあります。
 * BufferedImageと互換性のあるAPIがあります。PNG画像をそのままマーカイメージ
   にしたり、撮影画像の一部を切り出す機能があります。

----------------------------------------------------------------------
 NyARToolkit License
----------------------------------------------------------------------


NyARToolkitは、商用ライセンスとGPLv3以降のデュアルライセンスを採用して
います。

GPLv3を承諾された場合には、商用、非商用にかかわらず、無償でご利用にな
れます。GPLv3を承諾できない場合には、商用ライセンスの購入をご検討くだ
さい。


 * GPLv3
   GPLv3については、LICENCE.txtをお読みください。

 * 商用ライセンス(日本国)
   株式会社 エム・ソフトにお問い合わせください。
   http://www.msoft.co.jp/pressrelease/press090928-1.html

 * 商用ライセンス(その他の国)
   商用ライセンスについては、ARToolWorks社に管理を委託しております。
   http://www.artoolworks.com/Home.html


----------------------------------------------------------------------
 外部ライブラリ
----------------------------------------------------------------------
NyARToolkitの使用する外部ライブラリは、以下の通りです。
新しいバージョンのものがあれば、そちらを使用してください。


 1. JMF JavaTM Media Framework 2.1.1e
    utils.jmf,sample.joglの実行に必要です。
    URL: http://www.oracle.com/technetwork/java/javase/download-142937.html

 2. QuickTime 7.5
    utils.qtの実行に必要です。
    URL: http://www.apple.com/quicktime/qtjava/

 3. Jogl
    utils.jogl,sample.joglの実行に必要です。
    URL: http://download.java.net/media/jogl/builds/archive/
    file   : jogl-1.1.1-rc8-xxxx-xxx.zip 

 4. java3d
    utils.java3d,sample.java3dの実行に必要です。
    URL: https://java3d.dev.java.net/binary-builds.html
    file:    java3d-1_5_1-xxxx-i586.exe


実行するプロジェクトによっては、全ての外部ライブラリを揃える必要は
ありません。必要なものだけをインストールしてください。


----------------------------------------------------------------------
 Getting started
----------------------------------------------------------------------
Eclipse環境に、NyARToolkit開発環境をインストールする方法を説明します。


 1.Eclipseで空のワークスペースを作成します。

 2.lib,sample,utilsディレクトリをワークスペースにインポートします。

 3.インポートしたプロジェクトのエラーを修正します。多くの場合、エラーは
   文字コードの不一致と外部JARファイルの参照ミスです。文字コードの不一致
   は、プロジェクトの文字コードをUTF8に変更することで解決します。
   外部JARファイルの参照ミスについては、外部ライブラリの章を参考にして
   下さい。
   
 4.Webカメラをコンピュータに接続してください。

 5.NyARToolkit.sample.joglのSimpleLiteMStandard.javaを実行して、
   マーカを撮影します。立方体が現れれば、インストールは正しく完了しています。

 1-4の手順については、http://sixwish.jp/Nyartoolkit/ に詳しい解説があります。

----------------------------------------------------------------------
 プロジェクトの概要
----------------------------------------------------------------------
Eclipseプロジェクトの概要です。

 * NyARToolkit
   NyARToolkitライブラリの本体です。基本的はJ2MEのAPIが有れば動きます。
   3つのソースフォルダがあります。srcには画像処理、数値計算クラス群が
   あります。src.markersystemには、複数のマーカを簡単に扱う為のMarkerSystem
   があります。src.rpfには、RealityPlatformを構成するクラス群があります。
   依存する外部ライブラリはありません。

 * NyARToolkit.sample.java3d
   Java3dを出力先とするサンプルアプリケーションです。1個のサンプル
   プログラムがあります。外部ライブラリは、Java3DとJMFに依存しています。

 * NyARToolkit.sample.jogl
   OpenGLでの代表的な利用方法を実装したサンプルです。
   srcには、MarkerSystemを使ったサンプルがあります。OpenGLのスケッチを
   使ったサンプルと、使わないサンプルがあります。
   src.oldには、以前の古い形式のサンプルプログラムがあります。
   src.rpfには、RealityPlatformを使ったサンプルプログラムがあります。

   通常は、src以下のサンプルだけで足りると思います。

   src/sketchの下には、色々なサンプルがあります。
   

 * NyARToolkit.sandbox
   お砂場です。実験プログラムや作りかけのコードなどを埋蔵しています。
   品質は未保証です（不具合等が多く放置されています）。
   testソースフォルダにあるサンプルプログラムは、RealityPlatformの試験
   に役立つかもしれません。

 * NyARToolkit.utils.j2se
   JavaSEに依存したヘルパークラス群と、テストプログラムがあります。
   BufferedImageをそのままNyARToolkitへ入力するためのクラスなどが
   あります。

 * NyARToolkit.utils.java3d
   Java3Dに依存したヘルパークラス群と、テストプログラムがあります。
   NyARToolkitの出力値のJava3dへの入力を支援します。

 * NyARToolkit.utils.jogl
   Joglに依存したヘルパークラス群と、テストプログラムがあります。
   NyARToolkitの出力値のJoglへの入力を支援します。

 * NyARToolkit.utils.qt
   QTJavaに依存したヘルパークラス群と、テストプログラムがあります。
   QuickTimeからのキャプチャを支援します。

----------------------------------------------------------------------
 NyARToolkitのパフォーマンス
----------------------------------------------------------------------

NyARToolkitは、ARToolKitの処理系のいくつかを差し替え、高速化を図ってい
ます。1マーカ検出時の性能では、アルゴリズムレベルで4倍、単純な速度比で
約2倍程度高速です。

3.0.0から追加されたRPF(RealityPlatform)を使用した場合、さらに1.5倍程度
の高速化が可能です。

RPFは不安定な為、特に問題が無ければ、MarkerSystemの使用をお勧めします。


----------------------------------------------------------------------
 FAQ
----------------------------------------------------------------------
 *Q1.Windows7でJMFの設定が保存できません。
   >JMFRegistryを、管理者権限で実行することで、保存ができるようになります。

 *Q2.2.5.3以前のNyARToolkitとそのまま差し替えできません。
   >いくつかの関数で、引数が変更になりました。サンプルファイルを参考に、
    関数コールを修正してください。

 *Q3.RealityPlatform(RPF)とは何ですか。使い方が判りません。
  >RPFは、マーカ系ARアプリケーションの為の、フレームワークです。これを
   使うと、未知のマーカを認識したり、マーカの環境プロパティに簡単に
   アクセスできるようになります。また、軽度のマーカのはみ出しや、部分破壊
   にも対応できます。
   ※4.0.0現在は、メンテナンスを停止しています。4.0.0から搭載されている、
     MarkerSystemの利用をお勧めします。
     
 *Q4.MarkerSystemとはなんですか。
  >複数のID/ARマーカを、出来る限り簡単に扱う為のフレームワークです。
  座標変換や画像取得などを簡単に行うことが出来ます。
  Processingのスケッチシステムを参考にしたスケッチシステムと組み合わせる
  ことで、以前と比較して楽にプログラムを作ることができます。

----------------------------------------------------------------------
 既知の不具合
----------------------------------------------------------------------
 1.RPFの姿勢フィードバックが未実装。
 2.RPFの輪郭線抽出系のノイズ処理が最小二乗法の為、遅延が大きい。
 3.RPFの輪郭線抽出系のアルゴリズム不備で、輪郭線のドリフト現象が発生する。
 4.RPFの二次元系の移動検出性能が低い。
 5.RPFのエッジ抽出が、ブラーに弱い。
 6.RPFの初期検出性能が、旧NyARToolkit系と比較して低い。
 
----------------------------------------------------------------------
 お問い合わせ
----------------------------------------------------------------------
NyARToolkitに関するお問い合わせは、wm(at)nyatla.jp までご連絡ください。
状況により、お返事が遅れることもあります。ご了承ください。

----------------------------------------------------------------------
 Special thanks
----------------------------------------------------------------------
加藤博一先生 (Hirokazu Kato, Ph. D.)
 http://www.hitl.washington.edu/artoolkit/

Prof. Mark Billinghurst
 http://www.hitlabnz.org/

arc@dmzさん
 http://digitalmuseum.jp/