# HascTool 利用者向けドキュメント

HASC Tool は、HASC (人間行動センシングコンソーシアム)が開発する行動情報処理のためのツールです。

データの収集から分析、利用、評価までを単一のツールで実現します。まだまだ荒削りな部分の多いツールですが、今後の成長をご期待くだ さい。

（展開先ディレクトリの直下にあるreadmeファイルは更新されません。最新の情報は、メニューの ヘルプ＞ようこそ からたどれるreadmeファイル、および http://hasc.jp/ で確認して下さい）

## HASC Toolの実行方法

- Windows版は hasctool/HascTool.exe、Mac版は hasctool/HascTool.app を実行すれば起動します
- 初回起動時に、ワークスペース（プロジェクトや設定を保存するディレクトリ）の場所を聞かれるので、適当な空ディレクトリを指定 して下さい
- ようこそページ（メニュー: ヘルプ>ようこそ）を表示し、指示に従ってサンプルプロジェクトをインポートして下さい
- HascToolを更新したい場合は、メニューの ヘルプ>更新の検査 を実行して下さい（Eclipseと同様）

## 波形ビュー付きテキストエディタ

- ラベルファイル（*.label）や、csvファイルを開くと、波形ビュー付きのテキストエディタ（LabelEditor / WaveEditor）で編集できます
- 波形ビューの +t, -t, +v, -v ボタンを押すと、表示する範囲を変更します
- 波形ビューの rt ボタンを押すと、時刻の左端が0になります
- 波形ビューの ?t ボタンを押すと、選択した時間範囲に含まれるデータをテキストエディタ上に表示します
- 波形ビューの +L ボタンを押すと、選択した時間範囲をテキストエディタに挿入します（LabelEditorのみ）
- プロジェクトエクスプローラのcsvファイルのコンテキストメニューから、「ラベルファイルの新規作成」を選ぶと、csvファイルに関連づけ られた新規ラベルファイルを作成できます

## HASC Logger Server

- HascLoggerアプリから、ログファイルを受信するサーバです
- ログを保存したいディレクトリをプロジェクトエクスプローラで選択し、ツールバーの(H)ボタンを押すと起動します
- bindするポート番号を指定します（Macの場合は、1024番以降にする必要）
- iPhoneの場合は設定アプリ>HascLogger、Androidの場合はHascLoggerのSettingsボタンを押して、設定 を変更します

- upload URLを、http://PCのIPアドレス:ポート番号/ に設定します

- HascLoggerアプリからログをUploadすると、PCのHascTool上にアップロードされたファイルが表示されます
- もう一度ツールバーの(H)ボタンを押すとサーバが停止します

## Audioファイルの同期再生

- HascLoggerアプリからアップロードしたAudioファイルを、LabelEditorの波形ビューと同期させて再生することができます。 （波形にラベル付けを行う際の参考用）
- Windowsの場合、wavファイル（HascToolでの再生するためのAudioファイル）を生成するために、事前に以下の準備が必要です。 Macの場合は不要なはずです（OSX標準のafconvertコマンドを使用）。

- FFmpeg（v0.6.2で動作確認済）をインストールして下さい

- FFmpegのWindows用バイナリは、例えば、Audacity の FFmpeg library (FFmpeg_v0.6.2_for_Audacity_on_Windows.exe) があります。

- 環境変数 HASCTOOL_FFMPEG_CMD に、ffmpeg.exe へのフルパスをセットして下さい。

- 例：C:\Program Files (x86)\Ffmpeg For Audacity\ffmpeg.exe
- 環境変数は、Windows7の場合、マイコンピュータのプロパティ > システムの詳細設定 > 環境変数 > ユーザ環境変数 で定義できます。

- HascLoggerアプリからのログのUpload時に、Audioファイルの形式（iPhone版はcaf（IMA4）, Android版は3gp）が、wavファイル（無圧縮）に変換されます。

- ログアップロード後でも、プロジェクトエクスプローラで、caf/3gpファイルのコンテキストメニューから「Audioファイルを変換」を選べ ば、再変換できます。
- 変換コマンドが終了しない場合（ユーザからの入力を待っている等）、HascToolがフリーズします。この場合は、変換コマンドのプロセス （ffmpeg や afconvertなど）を強制終了すれば、HascToolは復活します。
- 手動で変換する場合の手順：

- afconvert（Mac用）を使う場合：afconvert -f WAVE -d LEI16 変換元ファイル 変換先ファイル.wav
- ffmpegを使う場合：ffmpeg -y -i 変換元ファイル 変換先ファイル.wav

- labelファイルに、以下のような形式でwavファイルの場所を記述します：
  #audiofile:$(projectRoot)/path_to/audio_file_name.wav; offsettime:0.4

- wavファイルが存在する状態で、プロジェクトエクスプローラのcsvファイルのコンテキストメニューから「Labelファイルの新規作成」を選 べば、上記テキストが自動的に挿入されます（offsettimeは適宜修正して下さい）。
- offsettime: は、加速度の波形とオーディオの時間のズレの調整用です。
- labelファイルではなく、加速度csvファイル（targetfileが指しているファイル）の方に、#audiofile:を書いても良い です。
- サンプルが、HascToolDataPrj の /SampleData/misc/audio-sample/ にあります。

- labelファイルをLabelEditorで開いて波形ビューを表示し、右側ツールバーのAuボタンをおすとオーディオ再生、もう一度押すと停止で す。

## hascxbdファイル（ブロック図）

- 複数のブロックを連結させた、ブロック図を作成することにより、様々なデータ処理を行う仕組みです
- プロジェクトエクスプローラのhascxbdファイルのコンテキストメニューから、「ブロック図を実行」を選ぶと、ブロック図を実行できます
- ツールバーの「BD停止」ボタンを押せば実行停止します
- 具体的なブロックの種類と使い方については、下記のブロックリファレンスを参照して下さい。

### ブロック図エディタ（新版）

- hascxbdファイルを開くと、ブロック図エディタが開きます

- 別のエディタが開いてしまう場合は、プロジェクトエクスプローラのコンテキストメニューで、アプリケーションから開く > BlockDiagram Editor 2 を選んで下さい

- 新規作成したい場合は、メニューから、ファイル > 新規 > その他 > HascXbd を選択して下さい。
- パレットで「Select」を選ぶと、オブジェクト（ブロックまたはコネクション）を選択するモードになります。（デフォルトでこのモード）

- プロパティビューで、選択したオブジェクト（１つのみ）の情報を変更出来ます

- ブロックのプロパティ（プリミティブ型または文字列型のもののみ）を設定できます

- ドラッグで、選択したオブジェクトを移動できます
- コンテキストメニューから「Delete」を選ぶ（または編集メニューから削除を選ぶ）と、選択したオブジェクトを削除できます
- 複数のオブジェクトを選択したい場合は、Shiftを押しながらオブジェクト順にクリックするか、ドラッグして矩形領域を一括選択して下さい
- オブジェクトを選択した後、（Ctrl+C、Ctrl+Vキーなどで）コピー＆ペーストができます。コピーの際には選択されているコネクションは 無視されますが、複数のブロックを選択してコピーすると、間にあるコネクションもコピーされます。

- Block Class List ビューから新規作成したいクラス名をダブルクリックすると、ブロックを追加できます。

- あるいは、パレットで「Block」を選び、ブロック図エディタ内をクリックすると、クラス名を入力してブロックを追加できます
- ブロックのNameプロパティで、ブロックの参照名（同一ブロック図内では重複不可）を指定して下さい
- ブロックのEnabledプロパティをfalseにすると、ブロックを無効（ブロックとそれに接続されたコネクションを削除したのと同じ効果）に できます。プロパティビューに、false/trueの代わりに、f や t と入力しても値を切り替えられます。

- パレットで「Conection」を選び、出力側ブロック（送信元）と入力側ブロック（受信先）を順にクリックすると、コネクションを追加できます

- プロパティビューで、inputPort / outputPort の名前を適宜指定して下さい

- パレットで「Comment」を選び、ブロック図エディタ内でドラッグすれば、コメント（実行には影響無し）を追加できます。

- コメントのテキストの変更するためには、コメントの図形をダブルクリックして下さい。もしくは、プロパティビューで、Textプロパティを変更 （クリックしてから右の[...]ボタンを押す）して下さい。

- hascxbdファイルをテキストとして編集したい場合は、プロジェクトエクスプローラのコンテキストメニューで、アプリケーションから開く > テキストエディタ を選んで下さい
- 時刻の単位は、microsecondsです。（1,000,000で1秒）
- ブロックの出力ポートには、通常、複数のコネクションを接続することができます。
- ブロックの入力ポートには、通常、単一のコネクションしか接続できません。複数入力のブロック（VectorConcatinatorなど）の場合 は、入力ポートの数をinputPortCountプロパティで設定し、各コネクションを、それぞれ inputPort[0], inputPort[1],… という名前の、別々のポートへと接続して下さい。

### 旧版のブロック図エディタ

- 旧版のブロック図エディタで編集したい場合は、プロジェクトエクスプローラのコンテキストメニューで、アプリケーションから開く > BlockDiagram Editor 1 を選んで下さい
- GraphViewタブを選ぶと、ブロック図がグラフで表示されます。

- +B ボタンを押すと、ブロックを新規作成できます。新規作成するブロックのクラス名を入力して下さい。
- Ctrl(control)キーを押しながら、出力側ブロック（送信元）と入力側ブロック（受信先）を順に選び、+Cボタンを押すと、コネクショ ンを新規作成できます。プロパティビューで、inputPort / outputPort の名前を適宜指定して下さい。
- Del ボタンを押すと、選択したブロック（それに接続されたコネクションを含む）またはコネクションを削除します。
- Inf ボタンを押すと、コメントなどのファイル情報を編集できます。
- ブロック図を変更した場合は、Ctrl+Sでファイルを保存してから、実行して下さい。
- Undo/Redoをしたい場合は、テキストエディタ（HascXBDタブ）に切り替えて行って下さい

### hascxbdファイル（XML）のフォーマット

- <model.BeanBlock>要素は、ブロックを表します

- <name>要素は、ブロックを参照するための名前です
- <class>要素で指定したクラスのインスタンスを生成し、プロパティに値をセットします。

- jp.hasc.hasctool.runtime.RuntimeBeanを実装した、JavaBeans準拠のクラ スである必要があります

- <properties>要素以下にプロパティの値を書きます

- <entry>要素は、1番目の子要素（<string>）がプロパティ名、2番目の子要素 （値によりタグが変わる）がセットする値です

- <model.Connection>要素は、<output>要素で指定された出力ポート と、<input>要素で指定された入力ポートを接続します。

- blockName属性はブロックの名前（<name>要素で指定したもの）
- portName属性はポートのプロパティ名

### Block Class List ビュー

- Block Class List ビュー内のクラス名をダブルクリックすると、アクティブなブロック図エディタにそのクラスのブロックを追加できます。
- 上部のテキストボックスに、テキストを入れてenterキーを押すと、クラス名を絞り込めます（大文字小文字を区別して部分一致検索。パッケージ名も 含めて検索）。テキストボックス上でESCキーを押すとリセットします。"/text/" のように書くと正規表現で、"/text/i" のように書くと大文字小文字を無視して正規表現で検索します。
- ウィンドウ > ビューの表示 > Block Class List で、ビューが表示されます

## labelファイル

- 時間区間にラベルをつけるためのデータ形式です。LabelEditorで編集できます。
- 基本的には、"開始時刻,終了時刻,ラベル" というフォーマットの、CSVファイルです

- ラベルに文字 ';' が含まれる場合、';' 以降の文字列はコメントとして扱われます

- ヘッダ

- #targetfile:

- labelファイルに関連づけられたcsvファイルのパス
- LabelEditor（のWave&Labelsタブ）でラベルを編集する際に、背景にこのcsvファイルの波形が表示される

- #labels:

- 以下のように使うラベルを列挙しておくと、LabelEditorでラベルの背景色が固定できる

- #labels:walk,jog,stay,stDown,stUp,skip

- RRGGBB または AARRGGBB 形式で、色の明示も可能

- #labels:walk(color=FFFF00),jog(color=4000FF00)

- #audiofile: 上記の「Audioファイルの同期再生」を参照

## 既知の不具合と対処方法

- LabelEditorの波形ビューで、ラベルの両端がそれぞれ左右の表示範囲外にある場合、ラベルの背景色が塗られません
- プロジェクトエクスプローラ上でファイルを開いた時に、別の種類のエディタが起動してしまう（または、他の種類のエディタでファイルを開きた い）場合は、コンテキストメニュー＞「アプリケーションからファイルを開く」を選んで下さい
- 外部でファイルを編集した場合は、プロジェクトエクスプローラを更新（コンテキストメニュー＞更新）する必要があります
- たまに、Refreshing workspace になったままになります

- BD停止 ボタンを押してタスクを止めれば、直るかもしれません

- 複数のスレッドから、同じフォルダをほぼ同時に作成しようとした場合、Exceptionが発生する場合が有ります。rawfile:（下記参照）を 使ってファイルシステムに直接出力すれば、改善するかもしれません。
- 実行中のブロックを強制終了した場合（停止ボタンを押した時に、HascToolが５秒程度フリーズしてからタスクが終了した場合）、 HascToolが不安定な状態になっている場合が有ります（ファイルを開いたままになっているなど）。動作が異常な場合、HascToolを再起動して 下さい。

## ブロックリファレンス

主要なクラスのみの抜粋です。

ソースファイル、ソースファイル付属のreadme_developer.html、サンプルのhascxbdファイルなども参考にして下さい。

### ポート名について（通常の場合。例外あり）

- 出力ポート名は outputPort

- 出力ポートは、複数の入力ポートへ接続できる。

- １入力ブロックの場合（通常はこちら）、入力ポート名は inputPort

- 入力ポートは、単一の出力ポートからしか接続できない

- 多入力ブロックの場合、

- 入力ポートの数を inputPortCount プロパティで設定する。
- 各コネクションを、それぞれ inputPort[0], inputPort[1], …, inputPort[ inputPortCount-1 ] という別々の名前のポートに接続する
- （任 意）primaryPortIndexプロパティで、時刻の同期に使う入力ポート（プライマリ入力ポート）のインデックスを指定できる。デフォルトは 0。他の入力ポートからの信号は、プライマリ入力ポートからの信号と時刻が一致するように、値が補間される（通常、線形補間）。

### ファイルのパスについて

- ファイルのパスは、"rawfile:"の場合を除き、ワークスペース内のリソース（フォルダ、ファイル）を指します
- "$(projectRoot)/"で始まる場合は、プロジェクトルートからのパス
- "/"で始まる場合は、ワークスペースからの絶対パス
- そうでない場合は、hascxbdファイルがあるディレクトリからの相対パス
- "rawfile:パス（ファイルシステム上の絶対パス）" という形式の場合は、ワークスペースではなく、ファイルシステムへの直接入出力を行います

- "rawfile:$(projectRoot)/相対パス"、"rawfile:$(workspaceRoot)/相対パス"という形式で、 プロジェクトルートまたはワークスペースからの相対パスを指定して、ファイルシステムへの直接入出力ができます
- 出力結果を反映させるためには、プロジェクトエクスプローラ上で「更新」を実行する必要があります

- ワークスペースにファイルを出力する場合、デフォルトでは、一旦全ての内容をメモリに貯めてから、最後に出力します。パスの前 に"unbufferedresource:"をつけると、メモリに貯めずに出力しますが、複数のファイルに対して同時に出力しようとすると、デッドロッ クが発生する場合があります（１つのファイルを出力完了するまで別のファイルには書き出せないため）。
- 以下のキーワードを含む場合は、ユーザに入力ファイル（複数可）を選択させ、それぞれのファイルに対してブ ロック図が順次実行 されます

- $(inputFile.path): 入力ファイルのパス
- $(inputFile.parentPath): 入力ファイルがあるフォルダのパス
- $(inputFile.name): 入力ファイル名（ディレクトリのパスは含まず）
- $(inputFile.nameWithoutExt): 入力ファイル名から拡張子を除いた名前

- その他のキーワード

- $(currentDateTime): 現在の時刻。形式は"日付-時刻-ms"

### Source系ブロック（出力ポートのみ）

- jp.hasc.hasctool.core.runtime.source.LineReaderSource

- ファイルから1行づつ読み取り、文字列系列として出力します。
- プロパティ

- filePath: ファイルのパス

- jp.hasc.hasctool.core.runtime.source.SinWaveGenerator

- 振幅1のサイン波を、スカラ信号（要素数１のベクトル信号）として出力します。
- プロパティ

- （必須）tickInterval: メッセージを出力する周期。例：10000 (10ms)
- （必須）tickEnd: 信号の出力を終了する時刻。例：10000000 (10秒)
- （必須）cycle: サイン波の周期。例：1000000 (1秒)

- jp.hasc.hasctool.core.runtime.source.UDPStringReceiver

- UDPで受信したパケットを、文字列系列として出力します。
- プロパティ

- port: UDPポート番号

### Sink系ブロック（入力ポートのみ）

- jp.hasc.hasctool.core.runtime.sink.LineWriterSink

- 文字列系列を入力し、ファイルに1行づつ書き出します。
- プロパティ

- filePath: ファイルのパス（出力先フォルダが無い場合、フォルダが自動生成されます）

- jp.hasc.hasctool.core.runtime.sink.XStreamLogSink

- 任意のオブジェクト系列を入力し、XML形式（XStreamでシリアライズ）でコンソールログに出力します。

- jp.hasc.hasctool.ui.views.RuntimeWaveView

- ベクトル信号の時系列変化を、HascTool上のビュー（WaveView）に表示します
- ベクトル値の各要素が、別々の色の波形として描画されます
- 横軸：時刻、縦軸：値
- プロパティ

- maxValue: 表示する値の範囲の上限
- minValue: 表示する値の範囲の下限
- name: 複数のWaveViewを開きたい場合、それを区別する名前

- jp.hasc.hasctool.ui.views.RuntimeVectorView

- ベクトル信号の瞬時値を、HascTool上のビュー（VectorView）に表示します
- ベクトル値の全要素が、単一の波形として描画されます。ベクトルの要素数が多い場合に使います
- 横軸：ベクトルのインデックス、縦軸：値
- プロパティは、RuntimeWaveViewと同様

### Filter系ブロック（入力ポートと出力ポートを持つ）

- jp.hasc.hasctool.core.runtime.filter.file.CSVToVectorFilter

- CSVファイルの文字列系列を入力し、ベクトル信号として出力します。
- プロパティ

- timeColumnIndex: 時刻カラムのインデックス。デフォルトは0。時刻カラムを除いた部分がベクトル値として扱われる
- timeUnitSeconds: 時刻カラムの単位（秒）。デフォルトは1.0

- jp.hasc.hasctool.core.runtime.filter.file.VectorToCSVFilter

- CSVToVectorFilterの逆です。ベクトル信号を入力し、CSVファイルの文字列系列として出力します。
- プロパティ無し

- jp.hasc.hasctool.core.runtime.filter.SleepFilter

- 入力された信号の時刻に合わせて、ブロックの処理を遅延して、そのまま出力するフィルタです。
- 一瞬でブロック図の結果が出てしまう場合に、間にこのフィルタを入れると、リアルタイムに再生しているように見えます

- jp.hasc.hasctool.core.runtime.filter.ScalarAdder

- ベクトル信号の各要素に、スカラ値（offsetプロパティ）を加算するフィルタです

- jp.hasc.hasctool.core.runtime.filter.ScalarMultiplier

- ベクトル信号の各要素に、スカラ値（offsetプロパティ）を乗算するフィルタです

- jp.hasc.hasctool.core.runtime.filter.VectorAdder

- 複数のベクトル信号を入力し、各要素を加算して、出力するフィルタです
- 例）入力値: [1,2], [3,4] => 出力値: [4,6]
- 多入力ブロック
- 入力するベクトル信号は、要素数が同一である必要

- jp.hasc.hasctool.core.runtime.filter.VectorConcatenater

- 複数のベクトル信号を入力し、全ベクトルの要素を連結して、出力するフィルタです
- 例）入力値: [1,2], [3,4] => 出力値: [1,2,3,4]
- 多入力ブロック

### ラベルファイル関連のブロック

- jp.hasc.hasctool.core.runtime.filter.file.CSVToLabelFilter

- CSVファイルの文字列系列をパースして、ラベル信号（LabelSignalMessage）として出力するフィルタです

- jp.hasc.hasctool.core.runtime.filter.file.LabelToCSVFilter

- CSVToLabelFilterの逆

- jp.hasc.hasctool.core.runtime.filter.ConcatenateVectorAndLabelFilter

- WaveViewに、ベクトル信号とラベルを合わせて表示したい場合、前段にこのフィルタをつなげます
- ベクトル信号用の入力ポート名：vectorInputPort
- ラベル信号用の入力ポート名：labelInputPort
- 出力ポート名（RuntimeWaveViewへ接続する）：outputPort

### 独自ブロックの開発用

- jp.hasc.hasctool.core.runtime.filter.AbstractFilter

- 1入力1出力のフィルタを作成する時に使う抽象クラス
- outputMessage(メッセージ); メソッドを呼び出すことにより、メッセージを出力します。

- jp.hasc.hasctool.core.runtime.sink.AbstractSink

- 出力無し、１入力のフィルタを作成する時に使う抽象クラス

- jp.hasc.hasctool.core.runtime.source.AbstractSource

- 入力無し、1出力のブロックを作成する時に使う抽象クラス

- jp.hasc.hasctool.core.runtime.filter.interpolator.AbstractMultipleInputsFilter

- 多入力1出力のフィルタを作成する時に使う抽象クラス

- jp.hasc.hasctool.core.runtime.filter.SampleFilter1

- AbstractFilterを使った、簡単な1入力1出力フィルタのサンプル

- jp.hasc.hasctool.core.runtime.filter.SampleFilter2

- 抽象クラスを継承しないで作られた、シンプルなフィルタのサンプル。スカラ値にvalutToAddプロパティの値を加算する

- jp.hasc.hasctool.core.runtime.filter.label.SampleLabelingFilter

- 入力値がしきい値より大きい期間に、ラベルをつけるフィルタのサンプル

## メッセージリファレンス

ブロック間でやりとりするメッセージのクラスです。

クラスは、jp.hasc.hasctool.core.data パッケージ以下にあります。詳細はソースファイルを見て下さい。

- 信号（SignalMessageクラス）

- 「信号メッセージ」を表すクラスの基底となる抽象クラスです
- 信号メッセージは、特定の時刻での信号の値を表しています。「時刻」と、その時刻での「値」を持ちます
- SignalMessageを出力する（別のブロックへ送信する）場合のプロトコル（メッセージ系列）：

- まず SignalMessage.BEGIN を送り、次に「時刻順」にSignalMessageを送り、最後に SignalMessage.END を送る必要があります。

- ベクトル信号（VectorSignalMessageクラス）

- 実数ベクトルの信号メッセージを表す抽象クラスです
- 生成方法：VectorSignalMessages#create()メソッドで生成して下さい

- スカラ信号（要素数1のベクトル信号）は ScalaSignalMessageクラス、それ以外は ArrayVectorSignalMessageクラス になります

- 複素数ベクトル信号（ComplexVectorSignalMessageクラス）

- 複素数ベクトルの信号メッセージです

- ラベル信号（LabelSignalMessageクラス）

- ラベルの開始／終了を表す信号メッセージです
- 生成方法：単一のラベルに対してLabelInfoクラスのオブジェクトを生成し、そのcreateBeginMessage() /createEndMessage()メソッドを呼び出して、開始／終了を表すLabelSignalMessageオブジェクトを生成し、時刻順 に出力して下さい

- 文字列系列（java.lang.Stringクラス）

- LineReaderSouceやLineWriterSinkとの通信に使います
- プロトコル：まず EnumCommand.BEGIN を送り、次に、１行づつに分割したjava.lang.Stringオブジェクトを順に送り、最後にEnumCommand.END を送ります。（時刻情報はありません）