Overview

HARKTOOL5はHARKで使う伝達関数やそれに必要なファイルを生成するコマンドラインツールの集合である。

依存関係

  • libharkio3

ワークフロー

伝達関数生成を行う場合、通常は次に示す手順が必要となる。

  1. マイクアレイ座標ファイル(xml形式)を作成
  2. 音源座標ファイル(xml形式)を作成
  3. 伝達関数の計算を実行

主な作業の流れと関連するコマンドは下図を参照のこと。

_images/harktool5_rst_flow.png

コマンド説明

harktool5

概要

伝達関数の作成に関する処理を行う。

指定された第一引数に応じて、入力ファイルを元に伝達関数ファイルを生成、もしくは伝達関数作成に関する計算を行う処理を実行する。

使用方法

harktool5 <function> <arguments>

  • <function>

    calctfimp インパルス録音から伝達関数を作成し、libharkio3(zip)形式で出力する
    calctfrec TSP録音から伝達関数を作成し、libharkio3(zip)形式で出力する
    calctfgeo 幾何計算から伝達関数を作成し、libharkio3(zip)形式で出力する
    calctfmouth くちTSP録音から伝達関数を作成し、libharkio3(zip)形式で出力する
    calcsysimp TSP録音をインパルス応答データに変換し、インパルス応答をチャネル毎にflt形式で出力する
  • <arguments> for calctfimp, calctfrec, calctfgeo

    --impulse-list インパルス録音の位置情報ファイル [calctfimp のみ] (e.g. impulse.xml)
    --tsp-list TSP録音の位置情報ファイル [calctfrec, calctfgeo のみ] (e.g. tsp.xml)
    --mic-list マイクアレイの情報ファイル (e.g. microphones.xml)
    --output-type
    伝達関数の種別を次から1つ選択
    LOC (定位用) / SEP (分離用) / LOC_SEP (両方)
     
    --output-file 出力ファイル名 (e.g. /path/tf.zip)
    --direct-length 直接音の長さ (default=32)
    --reverb-length 反響音の長さ [calctfimp, calctfrec のみ] (default=256)
    --normalize-src
    音源軸の正規化の有無を指定
    1(有効) / 0(無効)
    (default=0)
    --normalize-mic
    マイクチャンネル軸の正規化の有無を指定
    1(有効) / 0(無効)
    (default=0)
    --normalize-freq
    周波数軸の正規化の有無を指定
    1(有効) / 0(無効)
    (default=0)
    --reset-mic
    チャンネル未指定のマイクをmicrophones.xmlから削除し、
    idを0から再設定する。(HARKTOOL4と互換出力)
     
    --logLevel
    ログ出力レベルの設定(次のうち一つを選択)
    E=ERROR / W=WARNING / I=INFO / D=DEBUG
    (default=E)
  • <arguments> for calctfmouth

    --tsp-list TSP録音の位置情報ファイル (e.g. tsp.xml)
    --mic-list マイクアレイの情報ファイル (e.g. microphones.xml)
    --output-type
    伝達関数の種別を次のうち1つ選択
    LOC (定位用) / SEP(分離用) / LOC_SEP (両方)
     
    --output-file 出力ファイル名 (e.g. /path/tf.zip)
    --direct-length 直接音の長さ (default=32)
    --reverb-length 反響音の長さ (default=256)
    --normalize-src
    音源軸の正規化の有無を指定
    1(有効) / 0(無効)
    (default=0)
    --normalize-mic
    マイクチャンネル軸の正規化の有無を指定
    1(有効) / 0(無効)
    (default=0)
    --normalize-freq
    周波数軸の正規化の有無を指定
    1(有効) / 0(無効)
    (default=0)
    --reset-mic
    チャンネル未指定のマイクをmicrophones.xmlから削除し、
    idを0から再設定する。(HARKTOOL4と互換出力)
     
    --end 伝達関数計算の終了位置 (サンプル)  
    --mch 音声原音のチャンネル番号 (default=0)
    --hop 伝達関数計算のシフト長 (default=1000)
    --headmargin インパルス応答の開始マージン値(サンプル) (default=0)
    --logLevel
    ログ出力レベルの設定(次のうち一つを選択)
    E=ERROR / W=WARNING / I=INFO / D=DEBUG
    (default=E)
  • <arguments> for calcsysimp

    --tsporigflt 原TSP信号ファイル(flt形式)  
    --tsporigwav
    原TSP信号ファイル(WAV形式)
    tsporigflt または tsporigwav のいずれかの指定が必須
     
    --tsporigchannel TSP使用チャンネルの選択(WAV形式 を指定した場合に有効) (default=0)
    --sigmax 最大信号値の指定(flt形式 を指定した場合に有効)  
    --samplebyframe フレーム毎のサンプル数 (default=16384)
    --syncaddfreq 同期加算回数 (default=16)
    --syncaddoffset 同期加算の開始位置に対するオフセット (default=16384)
    --searchoffset
    同期加算の開始位置を指定した範囲で探索して使用
    (探索範囲の開始位置,終了位置をカンマ区切りで指定)
     
    --outchannellist 計算対象のチャンネルリスト(0始まり) (e.g. 0,1,....)
    --inputwave 入力ファイル(WAV形式)  
    --outputpath
    出力ファイルの接頭辞
    指定したパスに”_チャンネル番号.flt” を付加したものが出力
    ファイル名となる
    (例:/path/outfile_0.flt /path/outfile_1.flt, ...)
    (e.g. /path/outfile)

出力

libharkio3(zip)形式の伝達関数ファイル、または、calcsysimpで計算したマイクチャンネル毎のfltファイルを出力する。

harktoolcli-conv-sm

概要

libharkio2(バイナリ)形式の分離行列ファイルを、libharkio3(zip)形式のファイルに変換する。

指定されたlibharkio2形式の分離行列ファイルのデータを読み取り、libharkio3形式としてファイルへ書き出す。 libharkio2形式の分離行列ファイルは position(座標情報)に対応するid属性を持たない。そのため、 libharkio3形式への変換を行うには、元のファイルとは別に、座標とidとの対応関係を示す情報を与える必要がある。 harktoolcli-conv-smでは、分離行列に対応する分離伝達関数ファイル(-s によって指定したzip形式のファイル)からこの情報を取得し、変換に利用する。

使用方法

harktoolcli-conv-sm [OPTIONS]* sepmatfile(binary) septffile(zip) outputfile(zip)

  • 引数

    sepmatfile libharkio2(バイナリ)形式の分離行列ファイル名 (e.g. input.sm)
    septffile 対応する分離伝達関数ファイル (e.g. sep.zip)
    outputfile 出力ファイル名 (e.g. output.zip)

出力

libharkio3形式の分離行列ファイル (zip形式)を出力する。

harktoolcli-conv-tf

概要

libharkio2(バイナリ)形式の伝達関数ファイルを、libharkio3(zip)形式のファイルに変換する。

指定されたlibharkio2形式の伝達関数ファイルのデータを読み取り、libharkio3形式としてファイルへ書き出す。 定位伝達関数と分離伝達関数のいずれか、もしくはその両方の指定が可能である。 伝達関数が双方とも指定された場合に書き出されるファイルは、両者の伝達関数のデータを含む単一のファイルとなる。

注釈

定位伝達関数と分離伝達関数のうち、前者のみの指定の場合、 出力されるzipファイルは .mat ファイル群を持つ localization/ ディレクトリと空の separation/ ディレクトリを含む(後者のみ指定の場合はその逆)。

一方、双方の伝達関数を指定した場合、 出力ファイルは localization/ と separation/ の両ディレクトリに対応する .mat ファイル群をそれぞれ含む。

使用方法

harktoolcli-conv-tf [OPTIONS]* outputfile(zip)

  • 引数

    -l libharkio2(バイナリ)形式の定位伝達関数ファイル名 (e.g. loc.tf)
    -s libharkio2(バイナリ)形式の分離伝達関数ファイル名 (e.g. sep.tf)
    outputfile 出力ファイル名 (e.g. output.zip)

出力

libharkio3(zip)形式の伝達関数ファイルを出力する。

harktoolcli-flt2multiwav

概要

旧.fltファイルを多チャンネルwavに変換する。

指定された複数のfltファイルを、それぞれ1つのチャンネルとしてwaveファイルにまとめて出力する。

fltファイルは、引数で列挙するか、ファイルリストを改行区切りで記載したテキストファイルで指定することができる(-l が必要)。

注釈

fltファイルは32 bit 浮動小数点型 RAW形式であること。

各fltファイルでサンプル数が異なる場合、最も少ないサンプル数で出力される。

引数でfltファイルとファイルリストの両方を同時に指定することはできない。

使用方法

harktoolcli-flt2multiwav [OPTIONS]* outfile [infile1 infile2 ...]

  • 引数

    outfile 出力するwavファイル名  
    infile1 infil2 ... 入力fltファイル (e.g. /path/to/tsp_ch1.flt)
    -l ファイルリストのテキストファイルパス (e.g. /path/to/list.txt)

出力

waveファイル(32bit 浮動小数点型 16000Hz形式)を出力する。

harktoolcli-genconfig

概要

configタグ(伝達関数生成に必要なxml要素の一つ)を持つxmlファイルを作成する。

使用方法

harktoolcli-genconfig [OPTIONS]* [outfile]

  • 引数

    outfile 出力するxmlファイル名  
    -c コメント  
    -s TSP録音の同期加算回数(回) (default = 16)
    -o TSPオフセット(サンプル数) (default = 0)
    -p ピーク探索範囲(カンマ区切り、1始まり) (default = 0,0)
    -n FFT長(サンプル数) (default = 512)
    -r サンプリング周波数(Hz) (default = 16000)
    -m 最大振幅の幅 (default = 32768)
    -l TSP長 (default = 16384)
    -t TSP原信号のファイルパス (e.g. /path/to/original.tsp)

出力

config タグを持つxmlファイルを出力する(ファイル指定がなければ標準出力する)。

harktoolcli-genneighbors

概要

positions タグを持つxmlファイルを元に、neighbors タグ(伝達関数生成に必要なxml要素の一つ)を持つxmlファイルを作成する。

使用方法

harktoolcli-genneighbors [OPTIONS]* infile [outfile]

  • <arguments>
    infile positions タグを持つxmlファイル名  
    outfile 出力ファイル名  
    -a
    アルゴリズム種別 (1に固定)
    1 : NearestNeighbor
    (default = 1)
    -n Positionそれぞれが保持できるNeighborの最大数 (default = 3)
    -t 近傍判定のための閾値 (default = 0.5)

出力

positions タグを持つxmlファイルを出力する(ファイル指定がなければ標準出力する)。

harktoolcli-genposxml

概要

positionsタグ(伝達関数生成に必要なxml要素の一つ)を持つxmlファイルを作成する。

使用方法

harktoolcli-genposxml <coordmodel> [<commonopt>] <arguments>

  • <coordmodel>

    ball 球形に配置
    circle 円形に配置
    cylinder 円筒状に配置
    grid 格子状に配置
  • <commonopt> (共通)

    --type
    Positionsの種別を次から選択
    tsp / impulse / noise / microphone / soundsource
    (default = soundsource)
    --output 出力ファイル名(省略時は標準出力)  
    --id
    Position構造体に割り振るidの開始番号
    複数のPositionにインクリメントしながら割り振る
    (default = 0)
    --path Positionに対応するWAVファイル名の指定  
    --channels
    出力チャンネル指定(カンマ区切り)
    –type=microphoneでは無効
    (e.g. 1,2,3,4)

注釈

pathの指定方法

フォーマット用の文字列を {STR:FORMAT} の形式で含めることが可能。置換用文字列は次の表の通り。

RADIUS ( 単位 m )
ELEVATION ( 単位 deg )
AZIMUTH ( 単位 deg )
X_AXIS ( 単位 mm )
Y_AXIS ( 単位 mm )
Z_AXIS ( 単位 mm )
HEIGHT ( 単位 mm )

(例) --path=filename_r{RADIUS:%01.2f}_a{AZIMUTH:%03.0f}.wav と指定し、AZIMUTHを0度から15度毎に増加させる場合、 各Positionタグのpath属性に次のような文字列が割り振られる:

filename_r1.00_a000.wav
filename_r1.00_a015.wav
filename_r1.00_a030.wav
filename_r1.00_a045.wav
...
  • <arguments> for ball

    --min-radius 球の半径の最小値 (>0)
    --max-radius 球の半径の最大値 (>0)
    --interval-radius 球の半径の増分  
    --min-elevation 仰角の最小値  
    --max-elevation 仰角の最大値  
    --interval-elevation 仰角の増分  
    --min-azimuth 方位角の最小値  
    --max-azimuth 方位角の最大値  
    --interval-azimuth 方位角の増分  
  • <arguments> for circle

    --min-radius 円の半径の最小値 (>0)
    --max-radius 円の半径の最大値 (>0)
    --interval-radius 円の半径の増分  
    --elevation 仰角の値  
    --min-azimuth 方位角の最小値  
    --max-azimuth 方位角の最大値  
    --interval-azimuth 方位角の増分  
  • <arguments> for cylinder

    --min-radius 底円の半径の最小値 (>0)
    --max-radius 底円の半径の最大値 (>0)
    --interval-radius 底円の半径の増分  
    --min-height 高さの最小値  
    --max-height 高さの最大値  
    --interval-height 高さの増分  
    --min-azimuth 方位角の最小値  
    --max-azimuth 方位角の最大値  
    --interval-azimuth 方位角の増分  
  • <arguments> for grid

    --min-x_axis x座標の最小値  
    --max-x_axis x座標の最大値  
    --interval-x_axis x座標の増分  
    --min-y_axis y座標の最小値  
    --max-y_axis y座標の最大値  
    --interval-y_axis y座標の増分  
    --min-z_axis z座標の最小値  
    --max-z_axis z座標の最大値  
    --interval-z_axis z座標の増分  

出力

positions タグを持つxmlファイルを出力する(ファイル指定がなければ標準出力する)。

harktoolcli-gentsp

概要

TSP信号の合成を行う。

使用方法

harktoolcli-gentsp [OPTIONS]* outfile

  • 引数

    -n TSP信号の繰り返し回数(回) (default = 16)
    -o TSPオフセット値 (default = 0)
    -r TSPのサンプリング周波数 (default = 16000)
    -s TSP入力ファイル(32 bit 浮動小数点型 RAW形式)のファイル名  
    -v 正規化時の最大振幅 (default = 正規化しない)
    outfile 出力ファイル名 (e.g. tsp16.wav)

出力

32 bit 浮動小数点型WAV形式ファイルを出力する。

harktoolcli-mat2csv

概要

行列ファイルの内容をテキスト(カンマ区切り)に変換する。

使用方法

harktoolcli-mat2csv infile [outfile]

  • 引数
    infile 行列ファイル (e.g. tf00001.mat)  
    outfile 出力ファイル    

出力

カンマ区切りのテキストをファイルに出力する(ファイル指定がなければ標準出力する)。

出力ファイル例:

  • INT32 の場合:

    3,4,10,10
    3,10,-10,4
    :
    :
    
  • COMPLEX の場合 (実部, 虚部, ... と交互に出力):

    1.000000,2.000000,2.000000,4.000000,3.000000,6.000000,4.000000,8.000000
    3.000000,0.000000,4.000000,0.000000,5.000000,0.000000,6.000000,0.000000
    :
    :
    

harktoolcli-mergexmls

概要

複数の xml を1ファイルに統合する。

harktoolcli-genconfig, harktoolcli-genposxml, harktoolcli-genneighbors によって生成されたxmlファイルを統合し、一つのxmlとして出力する。ただし、ノードに重複がある場合は、エラーを表示して終了する。

使用方法

harktoolcli-mergexmls [OPTIONS]* xml1 xml2 [xml3 ...]

  • 引数
    -o 統合結果を出力するファイル名  
    -l ノードに重複がある場合でもエラーにはせず、後の引数で指定したノードの値を採用する  
    xml1,xml2,... 統合元のxmlファイル名  

出力

xml形式テキストをファイルに出力する(ファイル指定がなければ標準出力する)。

harktoolcli-validtf

概要

伝達関数ファイルのバリデートを行う。

指定されたファイルについて、(1)ファイルがzip形式である、(2)zip内のファイル構成が正しい、および、 (3)harkio関数でのデータ読込が可能である、という条件を満たした場合、バリデート成功とする。

使用方法

harktoolcli-vaildtf [OPTIONS]* infile

  • 引数

    -s 伝達関数の詳細情報を表示  
    infile バリデート対象のファイル  

出力

成功した場合、終了ステータスに0を返す。
ファイルの読み込みを失敗した場合、エラーメッセージを出力し、終了ステータスに0以外を返す。

harktoolcli-validxml

概要

Hark xml形式ファイルのバリデートを行う。

指定されたファイルについて、(1)harkio関数でのデータ読込が可能である、および、(2)内容(configタグ, positionsタグ, neighborsタグ)に不足がない、という条件を満たした場合、バリデート成功とする。

使用方法

harktoolcli-validxml [OPTIONS]* infile

  • 引数
    infile バリデート対象のファイル  
    -m infileをmicのpositonファイルとしてバリデートする  
    -s infileをsrcのpositonファイルとしてバリデートする  

出力

成功した場合、終了ステータスに0を返す。
ファイルの読み込みを失敗した場合、エラーメッセージを出力し、終了ステータスに0以外を返す。

harktoolcli-zip2coord

概要

伝達関数ファイルの数値列を読み込み、テキスト(カンマ区切り)に書き出す。

使用方法

harktoolcli-zip2coord [OPTIONS]* infile [outfile]

  • <arguments>

    -t
    伝達関数の種別
    LOC (定位伝達関数) / SEP (分離伝達関数)
    (default=LOC)
    -z
    Z軸の出力方法を次から選択
    amp (振幅) / db (デシベル dB) / phase (位相)
    (default=amp)
    -i 逆フーリエ変換結果を出力(Z軸=実数値)  
    infile 入力ファイル名(伝達関数zip)  
    outfile 出力ファイル名(CSV)  

出力

テキストファイルに出力する(ファイル指定がなければ標準出力する)。

出力例:

id,mic,x,y,z
0 , 0 , 1.000, 2.000, 3.000
0 , 1 , 2.000, 3.000, 4.000
:
: