harktool5 0.1 documentation

Overview

«  Welcome to harktool5’s documentation!   ::   Contents

Overview

harktool5 is a set of command line tools for preparing files (e.g., transfer functions) for HARK.

These are the CLIs that harktool5 supports.

Dependency

  • libharkio3

Workflow

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

  1. マイクロホン位置を表すファイル(xml形式)を作成
  2. インパルス応答リストファイル、または、TSP応答リストファイル(xml形式)を作成
  3. 伝達関数の計算を実行

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

_images/harktool5_rst_flow.png

Command Descriptions

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. microphone.xml)
    --output-type
    伝達関数の種別を次から1つ選択
    LOC (定位伝達関数) / SEP (分離伝達関数)
     
    --output-file 出力ファイル名 (e.g. /path/tf.zip)
    --direct-length 直接音の長さ  
    --normalize-src
    音源軸の正規化の有無を指定
    1(有効) / 0(無効)
     
    --normalize-mic
    マイクチャンネル軸の正規化の有無を指定
    1(有効) / 0(無効)
     
    --normalize-freq
    周波数軸の正規化の有無を指定
    1(有効) / 0(無効)
     
    --logLevel
    ログ出力レベルの設定(次のうち一つを選択)
    ERROR / WARNING / DEBUG / INFO
    (default=ERROR)
  • <arguments> for calctfmouth

    --tsp-list TSP録音の位置情報ファイル (e.g. tsp.xml)
    --mic-list マイクアレイの情報ファイル (e.g. microphone.xml)
    --output-type
    伝達関数の種別を次のうち1つ選択
    LOC (定位伝達関数) / SEP(分離伝達関数)
     
    --output-file 出力ファイル名 (e.g. /path/tf.zip)
    --direct-length 直接音の長さ  
    --start 伝達関数計算の開始位置 (サンプル)  
    --end 伝達関数計算の終了位置 (サンプル)  
    --mch チャンネル番号 (1始まり)  
    --nch チャンネル数  
    --fltlen 伝達関数出力のサンプル数  
    --hop 伝達関数計算のシフト長  
    --headmargin インパルス応答の開始マージン値(サンプル) (default=0)
    --enable-wn
    白色ノイズの追加
    1(有効) / 0(無効)
     
    --wn-level 白色ノイズのノイズレベル (enable-wn有効時)  
    --enable-normalize
    伝達関数の正規化
    1(有効) / 0(無効)
     
    --direct-length 直接音長  
    --logLevel
    ログ出力レベルの設定(次のうち一つを選択)
    ERROR / WARNING / DEBUG / INFO
    (default=ERROR)
  • <arguments> for calcsysimp

    --tsporigflt 原TSP信号ファイル(flt形式)  
    --tsporigwav
    原TSP信号ファイル(WAV形式)
    tsporigflt または tsporigwav のいずれかの指定が必須
     
    --tsporigchannel TSP使用チャンネルの選択(WAV形式 を指定した場合に有効)  
    --sigmax 最大信号値の指定(flt形式 を指定した場合に有効)  
    --samplebyframe フレーム毎のサンプル数 (e.g. 16384)
    --syncaddfreq 同期加算回数 (e.g. 16)
    --syncaddoffset 同期加算の開始位置に対するオフセット  
    --searchoffset
    同期加算の開始位置を指定した範囲で探索して使用
    (探索範囲の開始位置,終了位置をカンマ区切りで指定)
     
    --outchannellist 計算対象のチャンネルリスト(0始まり) (e.g. 0,1,....)
    --inputwave
    入力ファイル(WAV形式)
    16bit / 24bit , 8ch / 10ch / 16ch , 16kHz のWAV形式に対応
    (48KHzには非対応)
     
    --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 -m <matfile> -s <sepfile> -o <outfile>

  • 引数

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

出力

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

harktoolcli-conv-tf

概要

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

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

Note

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

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

使用方法

harktoolcli-conv-tf [-l <locfile>] [-s <sepfile>] -o <outfile>

  • 引数

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

出力

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

harktoolcli-genconfig

概要

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

使用方法

harktoolcli-genconfig <outfile> -t <tsppath> [<arguments>]

  • 引数

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

出力

config タグを持つxmlファイルを出力する。

harktoolcli-genneighbors

概要

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

使用方法

harktoolcli-genneighbors <arguments>

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

出力

positions タグを持つxmlファイルを出力する。

harktoolcli-genposxml

概要

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

使用方法

harktoolcli-genposxml <coordmodel> <commonarg> <arguments>

  • <coordmodel>

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

    --type
    Positionsの種別を次から選択
    tsp / impulse / noise / microphone / soundsource
    --output 出力ファイル名
    --id
    Position構造体に割り振るidの開始番号
    複数のPositionにインクリメントしながら割り振る
    (ただし、 -1 が指定された場合は全てのPositionのidに -1 を設定する)
    --path Positionに対応するWAVファイル名の指定

Note

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 <outfile> <arguments>

  • <arguments>

    <outfile> 出力ファイル名 (e.g. tsp16.wav)
    -s TSP入力ファイル(32 bit 浮動小数点型 RAW形式)のファイル名  
    -r TSPのサンプリング周波数 (e.g. 16000)
    -n TSP信号の繰り返し回数(回) (e.g. 16)
    -o TSPオフセット値 (e.g. 0)

出力

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

harktoolcli-ifftTF

概要

伝達関数ファイルの数値列に対するフーリエ逆変換の計算結果(実数値のみ)を テキスト(カンマ区切り)に書き出す。

使用方法

harktoolcli-ifftTF -t <tftype> -i <zipfile> [-o <outfile>]

  • 引数
    -t
    伝達関数の種別
    LOC (定位伝達関数) / SEP (分離伝達関数)
     
    -i 入力ファイル(zip形式)のファイル名  
    -o 出力ファイル名  

出力

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

harktoolcli-mat2csv

概要

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

使用方法

harktoolcli-mat2csv <infile> [-o <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 [-o <outfile>] <xml1> <xml2> [<xml3> ...]

  • 引数
    <xml1>,<xml2>,... 統合元のxmlファイル名  
    <outfile> 統合結果を出力するファイル名  

出力

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

harktoolcli-validtf

概要

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

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

使用方法

harktoolcli-vaildtf <infile>

  • 引数

    <infile> バリデート対象のファイル  

出力

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

harktoolcli-validxml

概要

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

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

使用方法

harktoolcli-validxml <infile>

  • 引数
    <infile> バリデート対象のファイル  

出力

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

harktoolcli-zip2coord

概要

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

使用方法

harktoolcli-zip2coord <arguments>

  • <arguments>

    -t
    伝達関数の種別
    LOC (定位伝達関数) / SEP (分離伝達関数)
    -z
    Z軸の出力方法を次から選択
    amp (振幅) / db (デシベル dB) / phase (位相)
    -i 入力ファイル(zip形式)のファイル名
    -o 出力ファイル名

出力

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

出力例:

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

Licenses

This software is distributed under HARK License

Changelog

2014.10.1 First version 0.1 released.

«  Welcome to harktool5’s documentation!   ::   Contents