= Pixel Module Metrologyのための画像のパターン認識 =

== 準備 ==
まず、作業（ディレクトリ構成、環境設定とコードのダウンロード）の仕方を説明する。

作業をするためのディレクトリを適当に作る。以下では、このディレクトリを$projDirと呼ぶ。このディレクトリの下に次のディレクトリを作る。
{{{
cd $projDir
mkdir scripts dev sw work
}}}
それぞれのディレクトリの役割は以下の通りである。
|| '''名前''' || '''用途''' ||
|| scripts || 初期設定用のスクリプト等をおく ||
|| dev || プログラムのソースコードを置いたり、コンパイル作業をする ||
|| sw || 開発したプログラムのインストール先 ||
|| work || プログラムを走らせるディレクトリ ||
このディレクトリ構成で作業を進めるために便利な設定をいくつかする。以下の内容をscripts/setup.shに記述して、ターミナルを立ち上げる度にsource ./scripts/setup.shでこれらの設定を作業環境に反映させる。
{{{
# scripts/setup.shの内容
export projDir=<projDir>
export SWDIR=${projDir}/sw # $projDirの名前で置き換える
export PATH=${SWDIR}/bin:${PATH}
export LD_LIBRARY_PATH=${SWDIR}/lib:${LD_LIBRARY_PATH}
export PYTHONPATH=${SWDIR}/python:${PYTHONPATH}
export LD_LIBRARY_PATH=/opt/opencv/lib64:${LD_LIBRARY_PATH}
export PYTHONPATH=/opt/opencv-4.5.5/lib/python3.6/site-packages:${PYTHONPATH}
}}}
次に、パターン認識のコードをGitから取ってくる。
{{{
cd $projDir/dev
git clone https://gitlab.cern.ch/atlas-jp-itk/pixel-module-metrology-analysis.git
}}}


== 使い方 ==
=== プログラムのコンパイル ===
パターン認識コード (pixel-module-metrology-analysis)は、Pythonのコードなのでコンパイルは不要であるが、複数のファイルをモジュール化しているため、これらを$projDir以下においておくと作業をしやすい。
{{{
cd ${projDir}/dev
mkdir build
cd build
cmake ../pixel-module-metrology-analysis
make install
}}}
これで、Pythonのプログラムやモジュールが$SWDIRの下にインストールされて、scripts/setup.shにある設定によって使用可能になるはずである。
------
''2023/06/02追記''
'''make installするとエラーが発生。'''
 {{{
 file INSTALL cannot make directory
 make: *** [Makefile:83: install] Error 1
 }}}
'''解決方法'''
 1. CMakeCache.txtの100行目あたりにある、
 {{{
 //Install path prefix, prepended onto install directories.
 CMAKE_INSTALL_PREFIX:PATH=/usr/local
 }}}
 を
 {{{
 //Install path prefix, prepended onto install directories.
 CMAKE_INSTALL_PREFIX:PATH=/nfs/space3/(・・・)/projDIR/sw
 }}}
 に手動で変更。

 2. dev/build/で、
 {{{
 make clean
 cmake ../pixel-module-metrology-analysis
 make install 
 }}}
------
=== プログラムの実行 ===
画像から直線や円を検出して、
{{{
cd $projDir/work
prec1.py -h
}}}
プログラムprec1.pyには、オプションを指定することで画像ファイル、パターン認識アルゴリズムのパラメータ等を変更できる。"-h"はヘルプを表示させるためのオプションで、これによってどのようなオプションが存在するかを確認できる。

B4 Metrologyで取得したデータは、/nfs/space3/tkohno/atlas/ITkPixel/Metrology/dataの下にディレクトリに保存されている。このパスを環境変数dataDirに設定するとして以下では進める。
{{{
export dataDir=/nfs/space3/tkohno/atlas/ITkPixel/Metrology/data
}}}
|| '''モジュール名''' || '''サブ・ディレクトリ名''' || '''内容''' ||
|| KEKQ15 || tray*picf* || サイズ、高さ測定用の写真 ||
|| KEKQ16 || tray*picf* || サイズ、高さ測定用の写真 ||
|| KEKQ17 || tray*picf* || サイズ、高さ測定用の写真 ||
|| KEKQ18 || tray*picf* || サイズ、高さ測定用の写真 ||

画像ファイルを指定して、直線検出をする方法
{{{
prec1.py -i $dataDir/KEKQ15/tray*picf*/ImgXXXX.jpg --wsum 20 --tgap 40
}}}

画像を表示させずにファイルに保存して終了する。パラメータをいろいろな値に設定して
{{{
prec1.py --tgap 20 --wsum 20 --target 'LineH,col3000,row2000' --figure-file lineh_tgap20.jpg -b > a20.log
prec1.py --tgap 20 --wsum 30 --target 'LineH,col3000,row2000' --figure-file lineh_tgap30.jpg -b > a30.log
prec1.py --tgap 20 --wsum 40 --target 'LineH,col3000,row2000' --figure-file lineh_tgap40.jpg -b > a40.log
}}}
のようにして画像を表示させず、ただプログラムを走らせて結果をファイルに残すことも可能である。

目標パターンを指定して実行したときに、検出されたパターン（点や線の数）の集計を出力するようにした。
{{{
prec1.py --input-file ../data/KEKQ18/tray-1picf_66/Img8988.jpg --tgap 30 --wsum 20 --target 'LineV,col1810,row2485'
prec1.py --input-file ../data/KEKQ18/tray-1picf_66/Img8988.jpg --tgap 30 --wsum 20 --target 'LineH,col1810,row2485'
}}}
目標の直線に載るはずだった点を数えるのに、おおよその座標（row, col）を指定する必要がある。

== パターン認識アルゴリズム ==
アルゴリズムのパラメータ

|| '''アルゴリズム名''' || '''パラメータ名''' || '''用途''' || '''初期値''' ||
|| !GapFinder || wsum || x,y方向にスキャンする際に点の前後で明るさの平均を取る幅 || 20 [pixels] ||
|| || tgap || ある点の前方wsum幅の平均と後方wsum幅の平均の差に対する閾値 || 40 ||
|| !SegmentFinder || connectDistMax || 点と点の間の距離 || 250 [pixels] ||
|| || cosAngleMin || 点が直線の向きと合っているか || 0.99 (~8度) ||
|| || distanceMax || 点と直線との距離 || 10 [pixels] ||
|| !LineFinder || || || ||
|| !PatternSelector || target || 目的とするパターンの名前 (LineH,col3000,row2000, Vertex,col1000,row3000等） || ||

== データの解析 ==
pmmAnalysis.pyを実行して画像を解析すると、画像ファイルの他にdata_pr1.pickleという名前のファイルが保存される。この中に画像認識の途中で作成されたヒストグラムなどのデータが保存されている。このファイルの中身を調べたり、中にあるヒストグラム（実際には配列）は、pmmInspect.pyというプログラムを使用して表示させることができる。
|| '''目的''' || '''コマンド''' ||
|| .pickleファイルの内容を表示する || pmmInspect.py -f ./data_pr1.pickle -l ||
|| .pickleファイルの中のスキャン結果を表示する || pmmInspect.py -f ./data_pr1.pickle -s scan1_x3500_diff ||


== 調べること ==
Asic, SensorおよびFlexの外形を検出するための最適なパラメータ設定を把握すること。そのためには、「最適なパターン検出」とは何かをちゃんと定義する必要がある。パターン認識アルゴリズムの出力からその性能を評価する指標としては以下のようなものが考えられる。
|| 点の数 ||
|| 線分（重複を除いた線）の数 ||
|| 角の数（線と線の交点） ||
|| 線の長さ ||
|| 線分を形成しない点の数 ||
|| 目的のパターン検出の成否 ||

多数の画像に対して、これらの指標を求めて傾向（分布、平均やばらつき）を調べる。その後、パラメータを変えてこれらの指標がどのように変化していくかを調べる。