file_io: Python OO → Rust FP 移行プラン

1. 概要と目的

現在 ScanDataPy/model/file_io.py には TsmFileIo / TbnFileIo / DaFileIo / HekaFileIO の 4 クラスがあり、いずれも コンストラクタ内でファイル I/O を実行し、結果を多数のインスタンス変数に 書き込む典型的な OO スタイルで書かれています。

本ドキュメントは、これを Rust の関数型プログラミング (FP) 強寄りのスタイルに 書き換えるためのプランを、両方の構造を図示しながら整理します。最終的には Python 側で AI による画像解析を行う構想があるため、境界 (PyO3) を意識した分離を 最初から設計に組み込みます。

※ Rust 言語仕様の詳細は別資料を参照: pub キーワード / derive マクロ

2. 現状の Python OO 構造と問題点

4 つのクラスが並び、TsmFileIo は内部で TbnFileIo をインスタンス化する 凝集度の高い構造になっています。

典型的な使われ方

# コンストラクタを呼んだ瞬間にファイル I/O が走り、
# 30 個近いインスタンス変数が mutate される
tsm = TsmFileIo(filename_obj, num_fluo_ch=2)
full, ch0, ch1 = tsm.get_3d()
elec = tsm.get_1d()  # 内部で elec_data_obj.get_data() を呼ぶ

問題点の整理

3. Rust FP 版の核アイデア (3 原則)

本リファクタの全体方針は次の 3 つの原則に集約されます。これらは独立ではなく、互いに支え合う関係にあります。

原則 1: 不変な struct でデータを表す

OO 版では self.full_frames = ... のように、生成後に値が書き換わるフィールドが多数ありました。 Rust FP 版では struct のフィールドは生成後に mutate しないことを徹底します。

#[derive(Debug, Clone)]
pub struct TsmHeader {
    pub num_x:       usize,
    pub num_y:       usize,
    pub num_frames:  u32,
    pub frame_interval_ms: f64,
}

全フィールドを pub にすれば getter メソッドを書く必要がなく、不変なので外部から読まれても問題ありません。 #[derive] マクロで Debug / Clone を自動実装するのが定石です。

原則 2: 操作は純粋な自由関数

OO 版の tsm.read_infor() のように self を mutate するメソッドではなく、 入力を取って出力を返すだけの関数として書きます。

// バイト列を渡すと、ヘッダ構造体を返す。それだけ。
// self も io も触らない、再現性 100%。
pub fn parse_tsm_header(bytes: &[u8; 2880]) -> Result<TsmHeader, ScanIoError> {
    // FITS 形式ヘッダから NAXIS1, NAXIS2, NAXIS3, EXPOSURE を抽出
    ...
}

同じ入力に対して常に同じ出力を返すため、ファイルなしでテストできるのが大きな利点です:

// テスト例: 実ファイルなしで小さなバイト列を渡して検証
#[test]
fn parses_minimal_header() {
    let bytes = make_test_header(64, 64, 100, 0.005);
    let header = parse_tsm_header(&bytes).unwrap();
    assert_eq!(header.num_x, 64);
}

原則 3: 副作用は最外層 1 関数に集約

ファイル I/O は open_tsm / open_tsm_pair / open_da 等の Adapter 層関数 1 つにだけ閉じ込めます。それ以外の関数は全て純粋。

pub fn open_tsm(path: impl AsRef<Path>) -> Result<ScanRecord, ScanIoError> {
    // ① 副作用: ファイル読み込み (この 1 行だけが I/O)
    let bytes = std::fs::read(path.as_ref())?;

    // ② 以下は全て純粋関数の合成
    let header = parse_tsm_header(&bytes[..2880].try_into()?)?;
    let raw    = raw_i16_from_bytes(&bytes[2880..], &header)?;
    let arr    = reshape_fortran_3d(raw, header.shape_with_dark())?;
    let arr    = axis_transform(arr);
    let (full, dark) = split_dark(arr);
    let full   = subtract_dark_frame(full.view(), dark.view());

    Ok(ScanRecord {
        source: SourceFormat::Tsm,
        fluo:   FluoData { full_frames: full, dark_frame: dark, num_fluo_ch: 2, ... },
        elec:   None,
    })
}

4. 共通出力型 ScanRecord

実際の研究データは 3 種類のファイル形式があり、それぞれ「画像データ」と「電気生理データ」の持ち方が違います。 この非対称性を低レベルで露呈させると、呼び出し側に形式ごとの分岐が漏れて API が汚れます。

解決策は、高レベル API が返す型を 1 つに統一することです。形式の違いは Adapter 層で吸収し、呼び出し側からは見えなくします。

5. 公開 API の階層

scandata-io が公開する関数は明確な役割分担を持ちます。利用者は通常、高レベル API だけを使えば済みます。

6. データ型の全体像

公開される struct と enum の定義を types.rs に集約します。 全て不変 (生成後 mutate なし) で、フィールドは pub 公開します。

// ===== 出力型 (公開) =====

#[derive(Debug, Clone)]
pub enum SourceFormat {
    Tsm,   // .tsm + .tbn ペア
    Da,    // .da 単一ファイル
}

#[derive(Debug, Clone)]
pub struct ScanRecord {
    pub source: SourceFormat,
    pub fluo:   FluoData,            // 画像は必ずある
    pub elec:   Option<ElecData>,   // 電気は無い場合もある
}

#[derive(Debug, Clone)]
pub struct FluoData {
    pub full_frames:       Array3<i32>,  // dark 減算済み (Y, X, N)
    pub dark_frame:        Array2<i16>,  // (Y, X)
    pub num_fluo_ch:       usize,         // チャネル数 (通常 2)
    pub frame_interval_ms: f64,
}
// 注: channels (チャネル別 4D 配列) は保持しない。
//     チャネル分離は domain 層 (builder) で split_channels() を呼び出して行う。

#[derive(Debug, Clone)]
pub struct ElecData {
    pub trace:        Array2<f64>,  // (sample, ch)
    pub num_ch:       usize,
    pub interval_ms:  f64,
    pub gain_table:   Vec<f64>,    // チャネル別ゲイン
}

// ===== 内部ヘッダ型 (公開だが主に内部使用) =====

#[derive(Debug, Clone)]
pub struct TsmHeader {
    pub num_x:             usize,
    pub num_y:             usize,
    pub num_full_frames:   u32,
    pub frame_interval_ms: f64,
}

#[derive(Debug, Clone)]
pub struct TbnHeader {
    pub num_elec_ch: usize,
    pub bnc_ratio:   f64,
}

#[derive(Debug, Clone)]
pub struct DaHeader {
    pub num_x:        usize,
    pub num_y:        usize,
    pub num_frames:   u32,
    pub bnc_ratio:    f64,
    pub interval_ms:  f64,
}

// ===== エラー型 (sum type) =====

#[derive(Debug, thiserror::Error)]
pub enum ScanIoError {
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),

    #[error("missing header key: {0}")]
    MissingHeaderKey(&'static str),

    #[error("invalid header value for {key}: {value}")]
    InvalidHeaderValue { key: &'static str, value: String },

    #[error("file too small: expected {expected} bytes, got {actual}")]
    FileTooSmall { expected: usize, actual: usize },
}

7. モジュール構造とクレート配置

クレートは scandata-io として ScanDataNet プロジェクトの workspace に置きます。 Adapter 層 1 段 + Domain 層 1 段の構造。

クレート構造 (実ファイル配置)

ScanDataNet/server/crates/scandata-io/
├── Cargo.toml
├── src/
│   ├── lib.rs          // 公開 API の再エクスポート
│   ├── io.rs           // 副作用層: open_tsm / open_tsm_pair / open_da
│   ├── header.rs       // 純粋: 3 形式のヘッダ解析
│   ├── frames.rs       // 純粋: reshape / axis_transform / subtract_dark
│   ├── elec.rs         // 純粋: TBN 電気生理解析
│   ├── da_sections.rs  // 純粋: DA の 3 section 分割
│   ├── types.rs        // データ struct / enum
│   └── error.rs        // ScanIoError
├── tests/
│   └── compat.rs       // .npy との bit-perfect 一致テスト
└── examples/
    └── tsm_info.rs     // CLI

8. データフロー: TSM

open_tsm() は「ファイルから生バイトを読む」副作用 1 ステップと、その後の純粋関数の合成として表現できます。 最終出力は ScanRecord。

コード例: open_tsm / open_tsm_pair の実装

pub fn open_tsm(path: impl AsRef<Path>) -> Result<ScanRecord, ScanIoError> {
    let bytes = std::fs::read(path.as_ref())?;
    let fluo = build_fluo_from_tsm_bytes(&bytes)?;

    Ok(ScanRecord {
        source: SourceFormat::Tsm,
        fluo,
        elec: None,
    })
}

fn build_fluo_from_tsm_bytes(bytes: &[u8]) -> Result<FluoData, ScanIoError> {
    let header_bytes: &[u8; 2880] = bytes.get(..2880)
        .ok_or(ScanIoError::FileTooSmall { expected: 2880, actual: bytes.len() })?
        .try_into()?;
    let header = parse_tsm_header(header_bytes)?;
    let raw    = raw_i16_from_bytes(&bytes[2880..], &header)?;
    let arr    = reshape_fortran_3d(raw, header.shape_with_dark())?;
    let arr    = axis_transform(arr);
    let (full, dark) = split_dark(arr);
    let full   = subtract_dark_frame(full.view(), dark.view());

    Ok(FluoData {
        full_frames:       full,
        dark_frame:        dark,
        num_fluo_ch:       2,
        frame_interval_ms: header.frame_interval_ms,
    })
}

// open_tsm_pair は同じ関数を再利用しつつ TBN も読む
pub fn open_tsm_pair(tsm_path: impl AsRef<Path>) -> Result<ScanRecord, ScanIoError> {
    let tsm_path = tsm_path.as_ref();
    let tbn_path = tsm_path.with_extension("tbn");

    let tsm_bytes = std::fs::read(tsm_path)?;
    let tbn_bytes = std::fs::read(&tbn_path)?;

    let fluo = build_fluo_from_tsm_bytes(&tsm_bytes)?;
    let elec = build_elec_from_tbn_bytes(&tbn_bytes, fluo.frame_interval_ms)?;

    Ok(ScanRecord {
        source: SourceFormat::Tsm,
        fluo,
        elec: Some(elec),
    })
}

9. データフロー: DA

DA は .tsm + .tbn と違い、imaging / elec / dark frame が 1 つのバイト列の中で連続配置されています。 これを副作用 1 ステップ + 純粋関数による section 分割で処理します。

コード例: open_da の実装

pub fn open_da(path: impl AsRef<Path>) -> Result<ScanRecord, ScanIoError> {
    let bytes = std::fs::read(path.as_ref())?;

    let header_bytes: &[u8; 5120] = bytes.get(..5120)
        .ok_or(ScanIoError::FileTooSmall { expected: 5120, actual: bytes.len() })?
        .try_into()?;
    let header = parse_da_header(header_bytes)?;
    let ranges = section_offsets(&header);

    let img  = parse_da_imaging_section(&bytes[ranges.img.clone()],  &header)?;
    let elec = parse_da_elec_section   (&bytes[ranges.elec.clone()], &header)?;
    let dark = parse_da_dark_section   (&bytes[ranges.dark.clone()], &header)?;

    let full = subtract_dark_frame(img.view(), dark.view());

    Ok(ScanRecord {
        source: SourceFormat::Da,
        fluo: FluoData {
            full_frames:       full,
            dark_frame:        dark,
            num_fluo_ch:       2,
            frame_interval_ms: header.interval_ms,
        },
        elec: Some(ElecData {
            trace:        elec,
            num_ch:       8,
            interval_ms:  header.interval_ms / header.bnc_ratio,
            gain_table:   header.gain_table(),
        }),
    })
}

10. 高レベル / 低レベルの責務分離

11. enum と trait の使い分け

12. OO vs FP 対比表

13. 移行ステップ

既存 PHASE_L1_TSM_PARSER.md のステップを本 FP 設計に整合させ、Stage 1〜3 で実装する順序です。

実装プランとの差分 (付録)

本ドキュメントは既存の実装プラン (ScanDataNet/PHASE_L1_TSM_PARSER.md および ScanDataNet/LEARNING_WEB_PROJECT_PLAN.md) を以下のように拡張・更新します:

14. 将来: Python (AI) との橋渡し

最終的に Python 側で AI による画像解析を行う構想があるため、Rust と Python の境界を 最初から見据えて 設計します。 ただし Stage 1〜3 では PyO3 連携は導入せず、純粋 Rust で完結させます。

なぜ「最初は PyO3 を入れない」のか

• PyO3 を入れると maturin ビルドが必須になり、純粋 Rust より複雑度が上がる
• 境界で型変換 (ScanRecord ↔ numpy.ndarray) を書く前に Rust 側ロジックを確定させたい
• ScanDataNet の主経路は WebSocket。Python 不要で完結する設計
• AI 解析の要件が固まった時点で scandata-io-py のようなクレートを追加するだけで済む構造にする

PyO3 連携を入れる時の最小ステップ (将来用メモ)

ScanDataNet/server/crates/
├── scandata-io/         // 純粋 Rust (現在のターゲット)
└── scandata-io-py/      // 将来追加: scandata-io をラップする PyO3 クレート
    └── src/lib.rs:
        use pyo3::prelude::*;
        use numpy::{IntoPyArray, PyArray3};

        // scandata-io の open_tsm_pair を Python から呼べる薄いラッパ
        #[pyfunction]
        fn open_tsm_pair_py(py: Python, path: &str) -> PyResult<Py<PyArray3<i32>>> {
            let record = scandata_io::open_tsm_pair(path)?;
            Ok(record.fluo.full_frames.into_pyarray(py).to_owned())
        }

作成 2026-05-17 · 最終更新 2026-05-18 (全面リライト) · ScanDataPy → ScanDataNet 移行計画の一部