GXII-LFEX Timing Analysis GUI

作成者：K.F.F. Law

このプロジェクトは、X線ストリークカメラデータからGXIIとLFEXの同期タイミングを解析するためのGUIアプリケーションです。

機能

• データ読み込み: XSCデータファイル（.txt形式）および IMG ファイルの読み込み
• IMG ファイルエンディアン制御: バイト順序を自動検出または手動設定（リトルエンディアン/ビッグエンディアン）
• データプレビュー: 生データを表示しながら領域設定を視覚的に調整
• インタラクティブ領域設定: GXII/LFEX領域をリアルタイムでプレビュー
• プリセット設定: よく使用する領域設定パターンをワンクリックで適用
• ユーザー設定自動保存: 変更した各種設定は config/user.yml に保存され、次回起動時に自動で復元
• リアルタイムパラメーター調整: GUI上で解析パラメーターを動的に変更
• 柔軟なピーク検出: 1ピーク・2ピーク検出モードの選択対応
• 自動ピーク検出: GXIIとLFEXの信号ピークを自動検出
• タイミング計算: GXIIピークを基準としたLFEXの相対タイミング計算
• 座標系修正: ヒートマップとピーク位置の正確な対応を実現
• 可視化: 生データ、処理済み信号、フィッティング結果のプロット
• 結果保存: 解析結果の画像を自動保存

セットアップ

簡単スタート（推奨）

1. スタートアップスクリプトを実行: ```bash

   Mac/Linux

   ./start_app.sh ```

   これで自動的に：

   • 既存プロセスのクリーンアップ
   • 仮想環境の検出・アクティベート
   • Streamlit環境の確認
   • GUIアプリケーションの起動 が実行されます。

2. ブラウザでアクセス: http://localhost:8502（自動的に開きます）

プロセス管理機能

問題: ポートが既に使用されている場合の対処

```bash

Mac/Linux

./startapp.sh --cleanup # 統合クリーンアップ（推奨） ./startapp.sh --status # 詳細な状態確認 ./cleanup_processes.sh # 専用クリーンアップスクリプト ```

自動機能: - 起動時に既存プロセスを自動クリーンアップ - 終了時のプロセス適切な終了処理 - Ctrl+C での安全な終了

---

手動セットアップ（上級者向け）

1. 必要なソフトウェア:

   • Python 3.8以上
   • pip パッケージマネージャ

2. インストール手順:

   ```bash

   リポジトリをクローンまたはダウンロード

   cd /path/to/LFEXTiming

   仮想環境を作成

   python3 -m venv venv

   仮想環境をアクティベート

   source venv/bin/activate # Mac/Linux

   必要なパッケージをインストール

   pip install -r requirements.txt `` **注意**: NumPy 2.0以上では互換性の問題が発生する可能性があります。requirements.txt` に記載されているバージョン制約に従ってください。

---

使用方法

GUIアプリケーションの起動

最も簡単な方法: bash ./start_app.sh # Mac/Linux

手動起動: bash source venv/bin/activate streamlit run main.py

アクセス

ブラウザで http://localhost:8502 にアクセス

---

クイックスタートガイド

1. アプリケーション起動: ./start_app.sh
2. ブラウザアクセス: http://localhost:8502
3. データファイル選択: 左側サイドバーでXSCファイルのパスを設定
4. プレビュー: 「🔍 領域設定をプレビュー」でデータを確認
5. 領域設定: 赤い矩形（GXII）と青い矩形（LFEX）を調整
6. 解析実行: 「解析実行」ボタンをクリック
7. 結果確認: グラフと数値結果を確認

---

詳細ドキュメント

データプレビュー機能

新機能として、解析前にデータをプレビューしながら領域設定を行うことができます：

• プレビュー表示: 「🔍 領域設定をプレビュー」ボタンでデータを表示
• 視覚的領域設定: 赤い矩形（GXII領域）と青い矩形（LFEX領域）で設定範囲を確認
• リアルタイム統計: 選択した領域の強度統計を表示
• プリセット設定: よく使う設定パターンをワンクリックで適用
• 設定ガイド: 効果的な領域設定のコツを表示

カスタマイズ可能な波形フィッティングシステム (v1.4.2新機能)

GXIIピーク検出に使用する波形をカスタマイズできる新しい波形システムを追加：

波形フィッティングオプション

• ガウシアン固定パルス (デフォルト): 従来のハードコード済み固定パルス幅
• ガウシアンFWHM入力: ユーザーが指定したFWHM（半値全幅）でフィッティング
• カスタムパルス波形: 実験データから取得した波形ファイルを使用

カスタム波形の使用方法

1. サイドバーの「波形設定」セクションで「カスタムパルス波形」を選択
2. 「波形ファイルをアップロード」で実験データファイル（CSV/TXT）をアップロード
3. ファイルプレビューで波形データを確認
4. 前処理オプション（正規化、補間係数）を設定
5. 通常通り解析を実行

対応ファイル形式

• CSV形式: time,amplitude または time,intensity の列構成
• TXT形式: タブ区切りまたはスペース区切りの2列データ
• データ要件: 最低50点以上、時間軸の単位は任意（自動正規化対応）

前処理機能

• 正規化: 波形の最大値を1に正規化
• 補間: データ点数を指定倍率で増加（滑らかな波形生成）
• 品質チェック: ファイル読み込み時の自動データ検証

活用場面

• レーザーパルス形状が標準ガウシアンと異なる場合
• より正確なフィッティングが必要な精密測定
• 特定の実験条件に最適化されたパルス波形の使用
• 実測波形データに基づく高精度解析

ファイル形式例

csv time,amplitude -2.0,0.001 -1.9,0.005 -1.8,0.015 ... 0.0,1.000 ... 1.8,0.015 1.9,0.005 2.0,0.001

1ピーク検出モード (v1.1.0新機能)

実験条件によって1つのLFEXピークしか観測できない場合に対応した新しい検出モードを追加：

ピーク検出モード選択

• 2ピーク検出 (デフォルト): 従来の動作を維持
• 1ピーク検出 (新機能): 単一ピーク専用モード

1ピーク検出時の選択オプション

• 最大強度: 検出された複数ピークの中から最も強度の高いものを選択
• 最初のピーク: 時間的に最も早いピークを選択
  
• 最後のピーク: 時間的に最も遅いピークを選択

使用方法

1. サイドバーの「LFEX検出モード」で「1ピーク検出」を選択
2. ピーク選択方法を指定（最大強度/最初のピーク/最後のピーク）
3. 通常通り解析を実行

活用場面

• レーザー出力調整により単一ピークのみ観測される場合
• ノイズにより第2ピークが不明瞭な場合
• 最も信頼性の高いピークのみを使用したい場合

パラメーター説明

ファイル設定

• データファイルパス: 解析するXSCデータファイルのパス
• 保存パス: 結果画像を保存するディレクトリ
• 画像を保存: チェックすると結果画像を自動保存

データプレビュー

• データプレビューを表示: プレビュー機能の有効/無効を切り替え
• 🔍 領域設定をプレビュー: データを読み込んでプレビュー表示

領域設定

• GXII領域: GXIIレーザーの信号を取得する矩形範囲（X最小, X最大, Y最小, Y最大）
• LFEX領域: LFEXレーザーの信号を取得するX範囲

処理パラメーター

• 回転角度: データを回転補正する角度（度）
• 移動平均ウィンドウ: ノイズ除去のための移動平均のサイズ
• GXII立ち上がり閾値: GXII信号の立ち上がりを検出する閾値

出力結果

数値結果

• ショットID（ファイル名から自動生成）
• GXIIピーク位置（ns）
• LFEXピークのタイミング（ns）
• GXIIピークに対するLFEXの相対タイミング差（ns）

グラフ

1. 生データ: 2Dヒートマップ表示
2. GXII信号: LFEX信号を差し引いた後のGXII信号とガウシアンフィット結果
3. LFEX信号: 検出されたピーク位置を表示

保存ファイル

画像保存が有効な場合、以下のファイルが生成されます： - {ショットID}_raw.jpg: 生データのヒートマップ - {ショットID}_gxii.jpg: GXII信号の解析結果 - {ショットID}_lfex.jpg: LFEX信号の解析結果

ファイル構成

LFEXTiming/ ├── main.py # メインのGUIアプリケーション ├── start_app.sh # 統一起動スクリプト (Mac/Linux) ├── requirements.txt # Python依存関係 ├── README.md # このファイル ├── venv/ # Python仮想環境 ├── config/ # 設定ファイル ├── data/ # データファイル (例: 波形データ) ├── debug/ # デバッグ用スクリプト ├── docs/ # 技術文書・リリースノート ├── logs/ # ログファイル ├── output/ # 出力結果 ├── scripts/ # その他のユーティリティスクリプト ├── src/ # ソースコード ├── testdata/ # テスト用データ └── tests/ # テストコード

トラブルシューティング

アプリケーションが起動しない

1. 仮想環境が正しくアクティベートされているか確認
2. 必要なパッケージがインストールされているか確認
3. ポート8502が他のプロセスで使用されていないか確認

データファイルが読み込めない

1. ファイルパスが正しいか確認
2. ファイルの読み取り権限があるか確認
3. ファイル形式がサポートされているか確認

保存先にアクセスできない

1. 保存先ディレクトリが存在するか確認
2. 書き込み権限があるか確認

元のノートブックとの対応

このGUIアプリケーションは GXIILFEX_Timing_20240625_reqpulse.ipynb の処理を完全に再現しており、以下の改善を加えています：

• v1.3.0での改善: プロジェクト構造の大幅整理と統一起動システム
• データプレビュー機能: 解析前にデータと領域設定を視覚的に確認
• 座標系の正確性: ヒートマップ表示とピーク位置の完全な対応
• パラメーターの動的調整: コードを編集せずにパラメーターを変更可能
• ユーザーフレンドリーなインターフェース: 直感的なWebベースのGUI
• エラーハンドリング: 不正な入力やファイルエラーに対する適切な処理
• 結果の構造化表示: メトリクス、グラフ、詳細結果の整理された表示

開発者向け情報

アーキテクチャ (v1.3.0)

• エントリーポイント: main.py - Streamlitアプリケーション
• ソースコード: src/ ディレクトリに整理されたモジュラー構造

主要な関数

• main(): Streamlitアプリケーションのエントリーポイント
• load_and_preview_data(): データ読み込みとプレビュー用処理
• create_preview_plot(): プレビュー用のヒートマップと領域表示
• process_timing_data(): メインの解析ロジック
• create_plots(): 結果グラフ生成ロジック

カスタマイズ

• Streamlitウィジェットの追加で新しいパラメーターを簡単に追加可能
• プレビュー機能のプリセット設定は簡単に変更・追加可能

依存パッケージ

• streamlit: Webベースのデータアプリケーション構築
• numpy: 数値計算
• matplotlib: グラフ描画
• scipy: 科学計算（信号処理、最適化）
• pandas: データ処理