Rgrainsの使い方 - keitaroyamada/Rgrains GitHub Wiki

日本語バージョンの説明書になります。

Rgrains

1. 導入

粒子の形状は、粒子の特徴を捉えるうえで最も基本的な情報の一つといえます。このような粒子の特徴は、粉体工学や堆積学など様々な分野で使用されています。特に堆積学では、大きさや形は、粒子の履歴や振る舞いを考えるうえで重要な情報として扱われています。

粒子の形状を定量的に示す試みは古くから行われてきました。その中でもWadell (1932)が定義した円磨度は有名です。円磨度は、粒子の凸部の曲率の平均をフィットする小円で表現し、その小円の平均半径を最大内接円の半径で割った無次元量で表される0-1の範囲の指標です。円磨度は、小円の半径の平均を使うことから、比較的ロバストな指標といえます。円磨度は、粒子の凸部に着目した指標で、粒子全体の形状に着目した円形度などと比較すると、より変化に敏感な指標といえます。それゆえに、円磨度は、堆積物粒子の識別やそれらの供給プロセスを考えるうえで重要な情報を提供してくれます。

しかしながら、複雑な形状を持つ天然の粒子の円磨度を定義に従って求めようとすると非常に難しく、また時間がかかることがわかります。コンピュータやデジタルカメラが普及する前は、Krumbein (1941)が提案した印象図を用いた迅速法が広く使用され、それは現在も続いています。この印象図の登場により、それまで主観的だった粒子形状情報にある程度客観的が加わり、比較研究が可能となり、研究分野が大幅に拡大したといえます。引用数からも、そのことがわかります。このような事実から、この印象図は時代的に大きな役割を果たした一方で、円磨度が本来持つ連続性を完全に表現できるものではなく、また、客観性も完全とは言えませんでした。

近年、コンピュータやカメラなどに代表されるデジタル技術の発達に伴って、円磨度を含む様々な粒子形状を客観的かつ高速に測定・計算することが可能になりつつあります。例えば、Zheng & Hryciw (2015) の円磨度を推定するアルゴリズムや、Fukuda & Naruse (2020) の楕円フーリエ解析アルゴリズムなどが挙げられます。このように、デジタル技術の発達に伴って、粒子形状解析はいままでにない速度と精度で可能となってきました。

Rgrainsは、画像中の粒子の輪郭抽出、形状解析、結果の出力といった一連の機能を含む画像解析ソフトです。画像中の粒子の長径、短径、円形度、面積などの計算が可能です。またこのソフトウェアは、Zheng & Hryciw (2015)のプログラムも内包しており、Wadellの円磨度の計算も可能です。この点においては、RgrainsはZheng & Hryciw (2015)をGUIで使用可能にしたラッパーソフトとも言えます。Zheng & Hryciw (2015)のプログラムはコアプログラムをMatlabかつコードとして公開したもので、利用にはハードルの高さがありました。Rgrainsはコーディングなしで円磨度の計算が可能なアプリで、気軽に解析を体験してもらえればと思っています。

実際の使用例としては、例えば、Ishimura & Yamada (2019) はRgrainsを使用した一番最初の事例で、津波堆積物中の礫の形状を解析し、地形の相似性と海浜礫の分布から過去の津波規模の推定を行いました。このように、Rgrainsは、粒子ダイナミクスの理解するうえで重要な情報を提供し、粒子の挙動の理解につながると考えています。私たちは、Rgrainsがいままでにない新たな視点を提供し、この分野におけるより深く、より包括的な理解の一助になればと思っています。

2. 計測および計算方法

2.0. 前処理

Rgrainsは画像内の粒子の形状を計測・計算することが可能です。この計測には二値化した画像を使用しておりますが、二値化した画像は粒子の輪郭を適切に再現している必要があります。二値化に適した画像の条件は、十分な解像度を持った画像(>300pix/cm)であること、全体の明るさが均質であること、被写界深度が十分高いこと、背景と粒子のコントラストが十分に大きいことが挙げられます。特に、長径は200pix以上であることが望ましいといえます。トレース台のようなバックライトの上に粒子を置いて撮影することで、明るさが均質で、コントラストが高い粒子の画像を得ることができます。最終的な二値化画像が流心の角を十分に表現できていれば、どのような撮影方法でも構いません。Rgrainsでは、入力された画像をMatlabの組み込み関数であるimbinarizeを用いて二値化します。詳細はリンク先をご確認ください。

2.1. 面積、長径、短径(中間径)、アスペクト比、円形度

Rgrainsでは、二値化後に各粒子とその周辺領域を切り出します。この時、'PCD normalisation'オプションが有効になっていると、この画像を外接円が指定した外接円の直径になるように画像をリサイズして正規化します。Rgrainsはこの画像からMatlabの組み込み関数regionpropsを使用して面積、長径、短径(中間径)、アスペクト比を計算します。また円形度は、'Circularity_type'オプションが'legacy'の場合、4piArea/Perimeter.^2で計算します。この結果は、R2022b以前と等価です。いっぽう、'Circularity_type'オプションが'new'の場合、regionpropsを使用して、円形度を計算します。

2.2.円磨度

2.2.1. 定義

円磨度の定義は以下のように非常にシンプルです。

$$Roundness = \left({1 \over n} \sum_{k=1}^n r_k \right)/R_{max}$$

ここで、 $R_{max}$ は最大内接円の半径, $n$ は角にフィットする小円の数、 $r_i$ は $i$ 番目のコーナーにフィットする小円半径を表します。

赤: 最大内接円

オレンジ: コーナーとなる凸部

緑: コーナーにフィットする小円

2.2.2. 計算アルゴリズム

Rgrainsでは、円磨度の計算アルゴリズムはZheng & Hryciw (2015)がオープンソースで公開しいているprogramを修正し、使用しています。詳細は論文に譲りますが、円磨度の算出に大きな影響を与えるプロセスは大きく分けて3つあります。

スムーズな輪郭の推定
Zheng & Hryciw (2015)のアルゴリズムでは、まずは初めに粒子の重心を中心に極座標に変換します。変換された輪郭は、ピクセルで構成されていたため、離散的な値を持っています。そのため、アルゴリズムでは、Matlabの組み込み関数smoothを使って、Loess法でスムージングを行っています。このプロセスで、Rgrainsでは 'trace_precision' と呼んでいるパラメータを使ってフィッティングを行っています。下の図は、'trace_precision(α)'を変化させたときのスムージング結果の違いを示しています。α = 0.3では不適合、α = 0.06では適合、α = 0.01では過適合していることが見て取れます。このα値は、スムージングに使用するwindowの幅(%)を意味しており、粒子の輪郭のスムージングに影響を与えます。値が減ると、スムージングがより局所的に行われるため、より細かな構造を再現する一方で、ノイズやテクスチャーなどの影響を受けやすくなります。最適なα値を指定することが重要です。

コーナーとなる凸部の検出
次に、このアルゴリズムでは、スムージング下輪郭から凸部のみを抽出します。この時使用されるパラメータをRgrainsでは'corner_sensitivity'と呼んでいます。このパラメータは、輪郭の点を結んだ弧と弦の高さ、すなわち矢高の許容限界値を意味しています。これを小さくすると、より小さなコーナーまで検出するようになります。下図は'corner_sensitivity'を変化させたときの小円の生成率の違いを示しています。定義上、小さな小円が生成されるほど、円磨度は小さくなるため、適切な値を探索する必要があります。

小円のフィッティングベストフィットな小円の算出には、輪郭の点から小円までの距離を最小二乗法で最小化することで得ています。小円の適合度は、Rgrainsで'circle_precision'と呼んでいる閾値を使用して、輪郭から小円の中心までの最小距離と小円の半径を比較して評価しています。下の図は'circle_precision'を変化させたときの小円のフィット状態を示しています。この値は、輪郭のコーナーに接する小円の決定精度を表す値です。小さい値にすると、許容値が大きくなり、よりラフなフィッティングを行うため、小円と輪郭がずれるようになります。基本的には高い方が望ましいですが、高い値を指定しすぎると、柔軟性がなくなり、小円を決定することができず、結果として、少ない小円から円磨度を計算することとなり、その精度が下がります。適切な値を選択することが重要です。

3. 動作確認環境

3.1. CUI版（クラス）および GUI版 (matlab app)

Matlab > 9.13

Image processing toolbox > 11.6

Curve Fitting Toolbox > 3.8

~~Statistics and Machine Learning Toolbox > 12.4~~　（v5.0.3から不要になりました）

~~computer vision toolbox > 10.3~~　（v5.0.3から不要になりました）

3.2. GUI版 (windows exe版)

Windows 10, 11 (Intel)

Matlab Runtime (Matlab Runtimeは無料で利用可能です。Rgrainsにはオンラインインストーラーがついています。)>

4. インストール

Rgrainsには3つのバージョンが存在します。それぞれのインストール方法は以下の通りです。

4.1. CUI版(Matlab code)

レポジトリのファイルをすべてダウンロードします。

解凍後、Matlabでディレクトリ全体を「パスに追加」します。

4.2. GUI版 (matlab app版)

Rgrainsのホームの右側にある「releases」から「Rgrains_vx.x.x_for_matlab.zip」をダウンロードします。

Matlabを起動し、アプリタブの「アプリのインストール」からダウンロードしたファイルを選択します。

4.3. GUI版 (windows exe版)

Rgrainsのホームの右側にある「releases」から「Rgrains_vx.x.x_for_windows.zip」をダウンロードします。

解凍後、Rgrains_vx.x.x_for_windows.exeを実行し、ウィザードに従ってインストールします。

5. 使い方

RgrainsにはCUI版とGUI版があります。以下、それぞれの使い方について概説します。それぞれのインストール方法については、インストールの項目をご確認ください。

5.1. CUI版(Matlab code)

Rgrainsはカプセル化されたクラスとして提供されます。簡単な使い方の例は、 'Simple_example.m' にあります。以下、この'Simple_example.m'を例に説明します。

5.1.1. インスタンスの作成

まず初めに、Rgrainsはカプセル化されたクラスとして提供されるため、Rgrainsのインスタンスを作成します。作成方法は以下の通りです。Rgrainsの機能は'rcalculator'に内包されます。
%インスタンスの作成
rg = rgrains();
5.1.2. 画像の読み込み

次に、インスタンスに解析する画像を読み込みます。画像の読み込みには 'loadImage()' メソッドを使用します。読み込み可能な画像の形式は[imread]>(https://jp.mathworks.com/help/matlab/ref/imread.html)を参照して下さい。必要であれば、 'uigetfile()' 関数を使用することで、GUIで画像のパスを取得することができます。読み込んだ画像は、 'im_in' プロパティに保持されます。
% 画像のパスを取得
[im_name, im_dir] = uigetfile();

% パスに基づき画像を読み込み
rg.loadImage(fullfile(im_dir, im_name));

% 読み込んだ画像を表示
figure
imshow(rg.im_in)
title('Input image')
5.1.3. 画像の二値化

Rgrainsでは、画像中の粒子を解析するために二値化画像を使用します。二値化方法の詳細は、imbinarizeを参照してください。二値化方法はデフォルトでは、 'adaptive' に設定されていますが、画像や被写体によっては、粒子の輪郭を正確に再現できない可能性があります。そのため、二値化した画像をチェックし、最適な設定をそれぞれの画像の撮影環境ごとに模索する必要があります。二値化の設定は、 'opts_binarise' プロパティから変更可能です。 'binariseImage()' メソッドは、 'opts_binarise' プロパティに基づいて二値化を実行します。二値化された画像は、 'im_bw' プロパティに保持されます。
% 二値化方法を設定
rg.opts_binarise = struct(...
                         'upconvert', true,...
                    'particle_color', 'Dark',...
                            'method', 'Otsu',...%['Adaptive', 'Otsu']
              'adaptive_sensitivity', 0.35,...
                  'noise_thresholds', [490 Inf],...
       'ignore_particles_on_borders', true);

% 二値化を実行
rg.binariseImage();

% 二値化した画像を表示
figure
subplot(1,2,1)
   imshow(rg.im_in)
   title('入力画像')
subplot(1,2,2)
   imshow(rg.im_bw)
   title('二値化画像')

[!TIP] 二値化のオプションは以下の通りです。

'upconvert' ["true", "false" (default: "true")] (heavy option)
画像のジャギーの影響を低減するため、画像を内挿し、二倍に拡大後、処理を行います。画像の拡大・内挿方法については、imresizeを参照してください。

'particle_color' ["Dark", "Bright" (default: "Dark")]
画像中の粒子の背景に対する相対的な明るさを指定します。例えば、背景が白、粒子が黒の場合、'Dark'をしています。

'method' ['Adaptive', 'Otsu' , 'Absolute', 'Edge', 'None'(default: "Adaptive")]
'Adaptive' ：画像を分割し、各領域に最適な値で二値化を行います。全体に明るさのむらがあるときに適しています。二値化方法の詳細はimbinarizeを参照してください。
'Otsu'：ヒストグラムに基づき、二値化を行います。画像に対して、粒子部分が大きいときに適しています。二値化方法の詳細はimbinarizeを参照してください。
'Absolute'：絶対値に基づき、二値化を行います。値は0-1で指定します。
'Edge'：独自の二値化法です。半透明な粒子などに適しています。全体をCanny法でエッジを検出し、エッジのモルフォロジー処理により粒子形状を取得します。また、Otsu法と組み合わせることで、輪郭の細部の再現性を上げています。ただし、細部の構造がつぶれやすいので注意が必要です。感度はCanny法の検出感度で、下限値は0.03、上限値は指定可能で、デフォルトでは0.05を使用しています。
'None'：何も処理を行いません。すでに二値化されている画像を入力するときに使用できます。ただし、二値化されているに見えてもRGB情報が残っている場合がありますので、使用前に画像のプロパティなどからご確認ください。

'adaptive_sensitivity', [0-1 (default: 0.35)]
二値化に使用する閾値を指定できます。二値化の方法が'adaptive'の場合は感度、'absolute'の場合は閾値、'edge'の場合は、エッジ検出感度の上限値として指定できます。詳細はimbinarizeを参照してください。

'noise_thresholds' [0-Inf (default: [490 Inf])] ($pix^2$)
粒子として検出する大きさの下限と上限を指定します。例えば、490-Infと指定した場合、 $490 pix^2$ 以下の粒子は無視されます。

'ignore_particles_on_borders' ["true", "false" (default: "true")]
画像の縁辺部に係った粒子を無視するかを指定できます。画像の縁辺部に係った粒子は全体を撮影できていないために、正確な形状を測定することができません。基本的には'true'でよいかと思います。

5.1.4. 円磨度の計算

円磨度やそのほかのパラメータは二値化された画像から計算されます。計測方法や計算方法の詳細については、手法の項目やや参考文献をご確認ください。円磨度の計算において、 'trace_precision', 'corner_sensitivity', 'circle_precision'はとくに重要なパラメータで、計算結果に大きな影響を与えます。したがって、これらのパラメータは慎重に決める必要があります。Adobe Illustorator用のサポートツール（RoundnessForAi）も用意していますので、ご活用ください。計算方法などの設定は、 'opts_roundness' プロパティから可能です。ここで設定したパラメータをもとに、 'calcRoundness()' メソッドを実行することで、円磨度の計算を実行できます。'calcRoundness()' メソッドは引数なしでも実行可能ですが、UIFigureハンドルを引数に取ることができ、引数がある場合は、UIFigure上にプログレスバーを表示します。
%　円磨度計算に必要なパラメータを設定
rg.opts_roundness = struct(...
                          'calc_roundness', true,...
                         'trace_precision', 0.0600,...
                      'corner_sensitivity', 0.0170,...
                        'circle_precision', 0.9960,...
                             'image_scale', 340,...
                       'PCD_normarisation', true,...
                                'PCD_size', 200,...
                        'Circularity_type', 'legacy');

% 計算を実行(プログレスバー付き)
f = uifigure();
rg.calcRoundness(f);
close(f)

[!TIP] 円磨度計算に利用できるオプションは以下の通りです。

'calc_roundness', ["true", "false" (default: "true")]
円磨度の計算を行うときは、'true'にします。円磨度の計算は非常に重い処理になります。このオプションを'false'にすると円磨度の計算をスキップし、長径やアスペクト比、面積、円形度のみを高速で計算することができます。

'trace_precision' [0-1 (default: 0.0600)]
ピクセルで構成された離散的な粒子の輪郭をLoess法でスムージングする際のパラメータです。例えば、0.06は全体の6%windowでスムーズ処理を行うことを意味しています。詳細については、smooth をご確認ください。

'Corner sensitivity' [0-1 (default: 0.0170)]
スムージングされた輪郭から角となる凸部を検出する際の感度です。

'Circle precision' [0-1 (default: 0.9960)]
検出した凸部にフィットする小円を決定する際に使用する精度です。

'Settings > Analysis > Apply PCD normarisation' ["true", "false" (default: "true")]
処理する粒子のサイズが極端に違うと、結果や計算速度に影響が出ます。この影響を避けるため、各粒子の外接円の大きさに基づいで画像のリサイズして規格化し、その後円磨度を計算します。この処理により、小さな粒子のフィッティングの向上と、大きな粒子の計算速度の向上が見込めます。この際、"Image scale"は自動的に最適化されますので、変更の必要はありません。

'PCD threshold' [0-Inf (default: 200)] ($pix$)
規格化に使用する外接円直径を指定できます。外接円の直径は、200pix以上が推奨値になります。

'Settings > Analysis > Use Circularity type' ["legacy", "new" (default: "legacy")]

5.1.5. 結果の表示

粒子の計測・計算された結果は、 'rprops' プロパティに保存されます。直接アクセスすることもできますが、 'makeResultImage()' メソッド、 >'makeResultTable()' メソッド、 'makeSummaryImage()' メソッドを使うことを推奨します。それぞれのメソッドの使い方は次の通りです。

'makeResultImage()'
抽出した輪郭、最大内接円、小円などをベースイメージの上に重ね書きします。
%結果の表示
rg.opts_plot = struct(...
                           'base_image', 'original',... 
  'colour_smoothed_particle_boundaries', 'magenta',...
'thickness_smoothed_particle_boundaries', 1.5,...
          'colour_max_inscribed_circle', 'red',...
       'thickness_max_inscribed_circle', 1.5,...
                'colour_corner_circles', 'cyan',...
             'thickness_corner_circles', 0.5,...
                     'colour_info_text', 'yellow',...
                  'font_size_info_text', 15,...
                                 'font', 'Arial',...
                            'plot_info', 'Particlenumber');


figure
rg.makeResultImage(gca);

[!TIP] オプションは以下の通りです。

'base_image' ["original", "bw", (default: "original")]
ベースとなる画像を指定できます。デフォルト値は'original'で入力画像を使用します。'bw'にすると、二値化した画像を使用します。

'colour_smoothed_particle_boundaries' [(default: 'magenta')]
スムージングした粒子の輪郭線の色を指定できます。色のオプションはplot_coloursを参照してください。

'thickness_smoothed_particle_boundaries' [(default: 1.5)] スムージングした粒子の輪郭線の幅を指定できます。

'colour_max_inscribed_circle' [(default: 'red')]
最大内接円の線の色を指定できます。色のオプションはplot_coloursを参照してください。

'thickness_max_inscribed_circle' [(default: 1.5)] 最大内接円の線の幅を指定できます。

'colour_corner_circles' [(default: 'cyan')]
小円の線の色を指定できます。色のオプションはplot_coloursを参照してください。

'thickness_corner_circles' [(default: 0.5)] 小円の線の幅を指定できます。

'plot_info' ['Particlenumber', 'Roundness' (default: 'Particlenumber')]
図に描画する情報を指定できます。粒子番号や円磨度など、rpropsに格納されている指標であれば描画することができます。

'colour_info_text' [(default: 'yellow')]
描画する文字の色を市でいすることができます。

'font' [(default: 'Arial')] 描画する文字のフォントを指定することができます。使用可能なフォントは、使用環境に依存します。

'font_size_info_text'* [(default: 15)] 描画する文字のサイズを指定できます。

"makeResultTable"
結果をまとめ、テーブルデータを作成します。
%テーブルの作成
results_table = rg.makeResultTable();
"makeSummaryImage"
結果を取りまとめ、統計情報などをヒストグラムとともに表示します。
%まとめの作成
SS = get(0, 'ScreenSize');

figure('visible','on','Position',[SS(1) SS(2) SS(3) SS(4)]);
rg.makeSummaryImage(gca)

5.1.6. 結果のエクスポート

結果をファイルとしてエクスポートします。使用可能なオプションは以下の通りです。

'save_bw_image' ["true", "false", (default: "true")]
二値化した画像を保存します。

'save_fitted_image_with_No'** ["true", "false", (default: "true")]
粒子番号を付与した画像を保存します。

'save_fitted_image_with_Roundness' ["true", "false", (default: "true")]
円磨度を付与した画像を保存します。

'save_fitted_image_vector' ["true", "false", (default: "true")]
円磨度計算に使用した輪郭、最大内接円、小円、円磨度を付与した画像をAdobe Illustratorなどで編集可能なベクトル形式(*.eps)で保存します。

'save_summary_image' ["true", "false", (default: "true")]
結果の統計情報をまとめた図を保存します。

'save_csv' ["true", "false", (default: "true")]
結果とをcsv形式として保存します。

'save_settings' ["true", "false", (default: "true")]
解析に使用したパラメータをすべて保存します。保存したパラメータは 'loadSettings()' メソッドを使用することで復元可能です。
% エクスポート設定
rg.opts_export = struct(...
                        'save_bw_image', true,...
            'save_fitted_image_with_No', true,...
     'save_fitted_image_with_Roundness', true,...
             'save_fitted_image_vector', true,...
                   'save_summary_image', true,...
                             'save_csv', true,...
                        'save_settings', true);

% エクスポートの実行
[save_dir] =uigetdir();
rg.export(save_dir)

5.2. GUI版(windows exe及びMatlab app版)

[!NOTE] インストールについては、インストールの項目をご確認ください。

5.2.0. 設定の保存・読み込み

[File > Save settings]
解析パラメータや描画の色などすべての設定を保存することができます。設定ファイルは拡張子「*.rgrains」で保存されます。中身はMatlabのMATファイルになます。バッチ処理の際>には、バッチ処理後に自動的に保存されます。

[file > Load settings]
保存した設定ファイルを読み込みすることができます。

5.2.1. 画像の読み込み

それではメインとなる画像の解析を始めましょう。複数の画像をバッチ処理する場合も、初めに一枚処理して、最適な解析パラメータを決定することが重要です。　　まず初めに解析する画像を１枚読み込みます。読み込みはアプリの左上にある [Load image] から行います。読み込める画像は指定した拡張子(e.g. *.jpg)に限られます。これは>バッチ処理でも同様です。対象とする画像の拡張子を変更したいときは、 [settings > Acquisition > image type] から変更が可能です。

5.2.2. 画像の二値化

Rgrainsでは、粒子の解析を二値化した画像で行います。粒子の正確な輪郭を抽出するために最も重要なプロセスです。粒子の端までしっかりと検出できていること、不要な物体(e.g.ゴミなど)を検出していないことを確認する必要がります。二値化は [Binarise] から行います。二値化はMatlab関数のimbinarizeに依存します。詳細こちらをご確認ください。二値化は、デフォルトでは"Adaptive"になっています。"Adaptive"は局所領域の明るさ分布に基づいて二値化を行うため、明るさにムラがあるときに有用です。しかし、例えば画像の1/3を占めるような大きな粒子を処理するときはうまく二値化できないなど、場合によっては輪郭をうまく再現できないなどの課題があります。以下の設定を使って、粒子の輪郭を十分い再現できる最適なパラメータを決定・使用してください。

[!TIP] 二値化のオプションは下記のとおりです。.

'Particle_color' ["Dark", "Bright" (default: "Dark")]
対象とする粒子の相対的な明るさを指定します。例えば、背景が白で粒子が黒色の場合は"Dark"を選択してください。

'Method' ['Adaptive', 'Otsu', 'Absolute', 'Edge', 'None' (default: "Adaptive")]
'Adaptive' ：画像を分割し、各領域に最適な値で二値化を行います。全体に明るさのむらがあるときに適しています。二値化方法の詳細はimbinarizeを参照してください。
'Otsu'：ヒストグラムに基づき、二値化を行います。画像に対して、粒子部分が大きいときに適しています。二値化方法の詳細はimbinarizeを参照してください。
'Absolute'：絶対値に基づき、二値化を行います。値は0-1で指定します。
'Edge'：独自の二値化法です。半透明な粒子などに適しています。全体をCanny法でエッジを検出し、エッジのモルフォロジー処理により粒子形状を取得します。また、Otsu法と組み合わせることで、輪郭の細部の再現性を上げています。ただし、細部の構造がつぶれやすいので注意が必要です。感度はCanny法の検出感度で、下限値は0.03、上限値は指定可能で、デフォルトでは0.05を使用しています。
'None'：何も処理を行いません。すでに二値化されている画像を入力するときに使用できます。ただし、二値化されているに見えてもRGB情報が残っている場合がありますので、使用前にプロパティなどからご確認ください。

'Sensitivity', [0-1 (default: 0.35)]
二値化の際の閾値を指定します。'Adaptive'の場合はこの値を感度, 'Absolute'の場合は閾値、'Edge'の場合はエッジ検出の上限感度として処理を行います。詳細についてはimbinarizeを参照してください。

'noise_thresholds' [0-Inf (default: [490 Inf])] ($pix^2$)
粒子の面積($pix^2$)に基づいて、採用する下限と上限を指定できます。例えば、490-Infと指定した場合、 $490 pix^2$ 以下の粒子を無視して二値化します。細かなゴミなどの除去が可能です。

'Image scale' [0-Inf (default: 340)] ($pix/cm$)
Rgrainsは、直径や面積などの解析結果をSI unitで返します。そのため、使用する写真の1 cmが何pixであるかを正確に指定する必要があります。物差しを撮影し、Photoshopで計測するなどして、スケールを入力してください。

'Settings > Binarisation > Upconvert' ["true", "false" (default: "false")] (heavy option) 画像はピクセルで構成されており、解像度が十分でない場合、ジャギーの影響が出やすくなります。このオプションでは画像を内挿し2倍に拡大して処理を行うことで、影響の低減を狙います。処理が非常に重くなりますので、適宜ご利用ください。また、このオプションを使用する場合、"Image scale"は内部で自動的に調整されるため、変更する必要はありません。画像の拡大方法については "imresize" をご確認ください。

'Settings > Binarisation > ignore particles on borders' ["true", "false" (default: "true")]
画像の端にかかって全体を撮影できていない粒子を無視するかを指定します。粒子の全体を撮影できていない場合、正確な解析ができないため、基本的にはこのオプションあh"true"がお勧めです。

5.2.3. 円磨度の計算

二値化した画像から、円磨度や長径などの計算を行います。 **[Analysis]**ボタンをクリックすることで実行されます。計算方法の詳細については、「測定及び計算方法」の項目をご確認ください。円磨度の解析には、"trace_precision", "corner_sensitivity", "circle_precision"が精度に最も大きく影響します。そのため、これらのパラメータは慎重に決定する必要があります。Adobe Illustrator上で動作するサポートツールも用意しておりますので、ご活用ください(RoundnessForAi)。

[!TIP] 円磨度の計算オプション以下の通りです。

'Trace precision' [0-1 (default: 0.0600)]
ピクセルで構成された離散的な粒子の輪郭をLoess法でスムージングする際のパラメータです。例えば、0.06は全体の6%windowでスムーズ処理を行うことを意味しています。詳細については、smooth をご確認ください。

'Corner sensitivity' [0-1 (default: 0.0170)]
スムージングされた輪郭から角となる凸部を検出する際の感度です。

'Circle precision' [0-1 (default: 0.9960)]
検出した凸部にフィットする小円を決定する際に使用する精度です。

'Settings > Analysis > Apply PCD normarisation' ["true", "false" (default: "true")]
処理する粒子のサイズが極端に違うと、結果や計算速度に影響が出ます。この影響を避けるため、各粒子の外接円の大きさに基づいで画像のリサイズして規格化し、その後円磨度を計算します。この処理により、小さな粒子のフィッティングの向上と、大きな粒子の計算速度の向上が見込めます。この際、"Image scale"は自動的に最適化されますので、変更の必要はありません。

'PCD threshold' [0-Inf (default: 200)] ($pix$)
規格化に使用する外接円直径を指定できます。外接円の直径は、200pix以上が推奨値になります。

5.2.4. 結果の描画

Rgrainsは円磨度の計算後、自動的に結果を右のスクリーンに描画します。線の色などは、 [Settings > Plot] から変更が可能です。また、[Replot]ボタンを押すことで、設定を反映して、再仰臥を行うことができます。

[!TIP] オプションは以下の通りです。

'Settings > Plot > Base image' ["original", "bw" (default: "original")]
描画の土台となる画像を指定できます。元の画像を使う場合は'original'、二値化した画像を使用する場合は'bw'を指定してください。

'Settings > Plot > Particle boundaries colour' [(default: "magenta")]
スムージング下粒子の輪郭の色を指定できます。

'Settings > Plot > Maximum inscribed circle colour' [(default: "red")]
最大内接円の色を指定できます。

'Settings > Plot > Corner small circles colour' [(default: "cyan")]
コーナーにフィットする小円の色を指定できます。

'Settings > Plot > Text colour' [(default: "yellow")]
円磨度やNoなどの文字の色を指定できます。

'Settings > Plot > Plot font' [(default: "Arial")] 円磨度やNoなどの文字のフォントを指定できます。使えるフォントは使用するPC環境によって異なります。

5.2.5. 結果のエクスポート

[Export] ボタンを押すことで、結果をエクスポートできます。エクスポートするデータの種類は [Settings > Export] から指定が可能です。

[!TIP] エクスポートのオプションは以下の通りです。

'Settings > Export > Save BW image' ["true", "false", (default: "true")]
二値化した画像(jpeg)を出力します。

'Settings > Export > Save fitted image with Number' ["true", "false", (default: "true")]
粒子番号を付与した画像を出力します。

'Settings > Export > Save fitted image with Roundness' ["true", "false", (default: "true")]
円磨度を付与した画像を出力します。

'Settings > Export > Save fitted image as vector' ["true", "false", (default: "false")]
円磨度の計算に使用した輪郭や最大内接円、小円などを描画した画像をAdobeIllustratorなどで編集可能なEPS形式で出力します。

'Settings > Export > Save summary image' ["true", "false", (default: "true")]
計測・計算結果をヒストグラムとして出力します。

'Settings > Export > Save csv' ["true", "false", (default: "true")]
計測・計算結果をテーブルデータとして出力します。画像から計算された粒子の平均Lab*も同時に出力できますが、正しい値を得るためには画像全体を均質な明るさにするとともに、事前に色を較正する必要があります。

'Settings > Export > Save settings' ["true", "false", (default: "false")]
Rgrainsで計測・計算に使用したすべてのパラメータ設定を画像ごとに出力します。バッチ処理の時、バッチごとにのみ設定ファイルを出力したいときは"false"のままで構いません。

'Settings > Export > Save annotation[___]' ["Roundness", "Circularity", "Major axis", "Minor axis" (default: "Roundness")]
計測・計算結果を深層学習で利用可能なVOC形式(*.xml)で出力します。

5.2.6. バッチ処理

フォルダに入ったすべての画像ファイルの分析を行いたいときは、バッチ処理を行います。 [Batch > Run from folder] をクリックすると実行し、画像フォルダ、保存フォルダを指定します。指定後は、すでに指定されたパラメータに基づいて画像の抽出、二値化、円磨度の計算、エクスポートが行われます。

6. 引用

引用例を以下に示します。

Rgrains自体、あるいは二値化やエクスポートを含む一連の処理など

Yamada, K. (2023). Rgrains[Computer software]. https://github.com/keitaroyamada/Rgrains.

We used the Rgrains (Version 5.0.0) to calculate the roundness.

二値化後の画像から円磨度を計算する方法、コアプログラム

Zheng, J., & Hryciw, R. D. (2015). Traditional soil particle sphericity, roundness and surface roughness by computational geometry. Géotechnique, >65(6), 494-506. (https://www.icevirtuallibrary.com/doi/abs/10.1680/geot.14.P.192).

[!NOTE] RgrainsはVer. 4.11.0までは非公開バージョンです。Rgrains(v5.0.0)はRgrains(v4.11.0)のメソッドをカプセル化し、依存ツールボックスやライセンスを整理したもので、主要なアルゴリズムに変更はありません。また、Rgrains(v5.0.0)はRgrains(v4.11.0)と同じ結果が得られることを確認しています。

Rgrainsの使い方 - keitaroyamada/Rgrains GitHub Wiki

Rgrains

1. 導入

2. 計測および計算方法

2.0. 前処理

2.1. 面積、長径、短径(中間径)、アスペクト比、円形度

2.2.円磨度

2.2.1. 定義

2.2.2. 計算アルゴリズム

3. 動作確認環境

3.1. CUI版（クラス） および GUI版 (matlab app)

3.2. GUI版 (windows exe版)

4. インストール

4.1. CUI版(Matlab code)

4.2. GUI版 (matlab app版)

4.3. GUI版 (windows exe版)

5. 使い方

5.1. CUI版(Matlab code)

5.1.1. インスタンスの作成

5.1.2. 画像の読み込み

5.1.3. 画像の二値化

5.1.4. 円磨度の計算

5.1.5. 結果の表示

5.1.6. 結果のエクスポート

5.2. GUI版(windows exe及びMatlab app版)

5.2.0. 設定の保存・読み込み

5.2.1. 画像の読み込み

5.2.2. 画像の二値化

5.2.3. 円磨度の計算

5.2.4. 結果の描画

5.2.5. 結果のエクスポート

5.2.6. バッチ処理

6. 引用

7. 参考文献

3.1. CUI版（クラス）および GUI版 (matlab app)