MICrONS data 使い方ガイド

1. 前提環境

2. セットアップ (初回のみ)

2-1. uv のインストール確認

本プロジェクトは uv (高速な Python パッケージマネージャ) を前提とする。インストール済みかは PowerShell で確認:

uv --version

未インストールなら公式手順でインストール:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2-2. 依存パッケージのインストール

プロジェクトフォルダに移動して uv sync を実行する。

cd "C:\Users\lunel\Projects\Programming\Python\MICrONS data"
uv sync

uv sync の動作:

1. pyproject.toml と uv.lock を読む
2. プロジェクト直下に .venv\ を作成 (なければ)
3. Python 3.13 を .venv\Scripts\python.exe に配置
4. caveclient / cloud-volume / numpy / pandas を .venv\Lib\site-packages\ に展開

完了後の重要なディレクトリ:

3. 仮想環境の有効化 / 無効化

uv で作った .venv は通常の Python venv と同じく、PowerShell から手動で有効化できる。有効化しなくても uv run 経由で実行できるが、対話的に複数コマンドを試したい場合は有効化すると便利。

3-1. 有効化 (PowerShell)

cd "C:\Users\lunel\Projects\Programming\Python\MICrONS data"
.\.venv\Scripts\Activate.ps1

成功するとプロンプトの左に環境名が付く:

(microns-data) PS C:\Users\lunel\Projects\Programming\Python\MICrONS data>

有効化されている間は python / pip が自動で .venv\Scripts\ 配下のものを指す。python --version で 3.13 が返ってくれば成功。

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

3-2. 無効化

環境を抜けるときは:

deactivate

プロンプトから (microns-data) が消えれば成功。PowerShell ウィンドウを閉じれば自動的に無効化される。

3-3. 環境を作り直したいとき

依存が壊れた / Python バージョンを変えたい場合:

deactivate                  # 有効化中なら先に抜ける
Remove-Item -Recurse -Force .venv
uv sync                     # 作り直し

4. CAVE 認証トークンの取得・保存

MICrONS データへアクセスするには CAVE のアカウント認証トークンが必要。初回のみ下記を実行する。

4-1. ブラウザでトークンを取得

uv run python get_token.py

ブラウザが開いて Google ログインを求められる。ログイン後、トークン文字列 (英数字 32 桁前後) が表示されるのでコピーする。

4-2. ローカルに保存

取得したトークンを環境変数 CAVE_TOKEN にセットしてから save_token.py を実行する:

$env:CAVE_TOKEN = "<your-token-here>"
uv run python save_token.py

成功すると次のように表示される:

Token saved. Verified connection to datastack 'minnie65_public'.

5. メッシュダウンローダーの起動 (3 パターン)

同じスクリプト microns_DL.py を走らせる方法は 3 通りある。状況に応じて使い分ける。

5-1. パターン A: uv run (もっとも簡単)

cd "C:\Users\lunel\Projects\Programming\Python\MICrONS data"
$env:PYTHONIOENCODING = "utf-8"
uv run python microns_DL.py

または PowerShell 全体を UTF-8 にしてから:

chcp 65001
uv run python microns_DL.py

5-2. パターン B: 仮想環境を有効化してから python で実行

ユーザが想定する「UV エンバイロメントを起動 → Python でスクリプト」のパターン:

cd "C:\Users\lunel\Projects\Programming\Python\MICrONS data"
.\.venv\Scripts\Activate.ps1

# 環境名が付いたら成功
(microns-data) PS> python --version
Python 3.13.x

# スクリプト実行
(microns-data) PS> $env:PYTHONIOENCODING = "utf-8"
(microns-data) PS> python microns_DL.py

# 終わったら抜ける
(microns-data) PS> deactivate

この方法だと、有効化中は python microns_DL.py の python が自動で .venv\Scripts\python.exe に解決されるので、システム Python と混ざる事故が起きない。

5-3. パターン C: 直接 .venv の python を叩く

cd "C:\Users\lunel\Projects\Programming\Python\MICrONS data"
.\.venv\Scripts\python.exe microns_DL.py

uv の依存解決サイクルを完全に飛ばすので、uv sync がロックエラー等で失敗している状況でも既存 .venv を使って動かせる。

5-4. パッケージとしてインストールした場合

uv pip install -e . を一度実行すると、コンソールスクリプト microns-data が登録される (pyproject.toml の [project.scripts] で定義済み)。これで:

(microns-data) PS> microns-data

とだけ打てば main.py が呼ばれ、内部で microns_DL.process_microns_data() が起動する。

6. 対話プロンプト 5 ステップの解説

起動すると次の順で質問される。Enter でデフォルト値を採用できる。

例: ID を 2 つだけ手動指定して全部デフォルト

Choice (1 or 2): 1
ID: 864691135572530981,864691135977309763
LOD (default: 3): Enter
Normalize mode [n/i/g] (default: n): Enter
Scale mesh (x20000)? (y/n) [y]: Enter
Add X, Y, Z scale bars? (y/n) [n]: Enter

7. normalize モード (重要)

3 ステップ目の normalize は出力結果の意味を大きく変える。複数ニューロンを 1 ファイルに連結する場合は特に注意。

8. 出力ファイル

カレントディレクトリ直下の mesh_out_precomputed2/ に書き出される。

OBJ 内では各ニューロンが o オブジェクトとして分離されている。オブジェクト名は通常 seg_<id> だが、microns_connect.py から役割情報 (id_groups) を渡すと <役割>__<id> (例 input__864...) になり、Blender 側でグループ分けに使える。

Blender で開く例:

1. Blender を起動
2. File → Import → Wavefront (.obj)
3. mesh_out_precomputed2\merged_keep_layout.obj を選択

9. シナプス / 細胞体クエリ (microns_DB.py)

あるニューロン (root_id) の細胞体位置と入力シナプスを取得したい場合:

uv run python microns_DB.py

デフォルトでは microns_DB.py 末尾の SAMPLE_TARGET_ID を対象に実行される。別の ID を調べる場合はその定数を書き換えるか、Python から関数を直接呼ぶ:

from microns_DB import report
report(864691135572530981)

出力には次が含まれる:

• 細胞体 (nucleus) 座標 (nucleus_detection_v0)
• 入力シナプス数
• 最大シナプス (スパイン) の ID / サイズ / 相手 (pre side) ID / 座標 (μm)
• サイズ上位 5 件

10. 結合錐体細胞の抽出と役割分け (microns_connect.py)

microns_connect.py は、ある起点ニューロンにシナプス結合している錐体細胞 (pyramidal cell) だけを集め、入力 / 起点 / 出力に役割タグと色を付けて 1 つの OBJ に書き出す橋渡しモジュール。microns_DB.py (シナプスクエリ) と microns_DL.py (メッシュ書き出し) を内部で連結している。

10-1. 基本の使い方

from microns_connect import get_connected_pyramidal_meshes

# 起点ニューロンに対し、入力(前シナプス)と出力(後シナプス)の
# 錐体細胞を両方集めて 1 つの OBJ に書き出す
get_connected_pyramidal_meshes(
    864691135572530981,
    direction="both",   # "input" / "output" / "both"
    max_partners=20,    # 方向ごとの上限
    lod=3,
)

または末尾の __main__ をそのまま使う:

uv run python microns_connect.py

10-2. 引数

10-3. 処理フロー

10-4. 錐体細胞の判定基準

細胞型は CAVE の aibs_metamodel_celltypes_v661 テーブルで判定する (列 classification_system / cell_type)。このボリュームでは興奮性ニューロンの cell_type は次の 7 種で、すべて錐体細胞 (末尾 P = pyramidal):

23P, 4P, 5P-ET, 5P-IT, 5P-NP, 6P-CT, 6P-IT

したがって「classification_system == "excitatory_neuron"」と「錐体細胞」はこのデータセットでは実質同義。microns_connect.PYRAMIDAL 集合でこの 7 種を保持しており、フィルタに使っている。

11. Blender で入力 / 起点 / 出力を区別する

microns_connect.py が書き出した OBJ では、各ニューロンが役割ごとに (1) オブジェクト名のプレフィックス・(2) 色 (MTL)・(3) OBJ グループ (g) の 3 重で区別されている。色の対応は次のとおり:

• target (起点) — 黄
• input (入力 / 前シナプス) — 青
• output (出力 / 後シナプス) — 赤
• both (相互結合) — 紫

これらは microns_DL.DEFAULT_GROUP_COLORS で定義されており、group_colors 引数で上書きできる。

11-1. Blender の「オブジェクトグループ」= コレクション

Blender でオブジェクトをまとめる仕組みは コレクション (Collection) だが、OBJ インポートではコレクションは自動生成されない。そこで付属の blender_organize.py を Blender 内で実行し、オブジェクト名のプレフィックス (input__ / target__ / output__ / both__) から自動でコレクションへ振り分ける。

11-2. 手順

1. get_connected_pyramidal_meshes(...) で OBJ を書き出す
2. Blender で File → Import → Wavefront (.obj) から merged_keep_layout.obj を読み込む (色は MTL 経由で付く)
3. 上部の Scripting タブを開く
4. Open で blender_organize.py を開き、Run Script (▷ ボタン)
5. Outliner に input / target / output / both コレクションが現れ、各ニューロンが振り分けられる

12. テスト実行

リファクタが壊れていないか確認するには:

uv run python -m unittest verify_refactor -v

6 件全て ok なら正常。テストは cloudvolume をモック化しているのでネットワーク不要・トークン不要で走る。

13. トラブルシューティング

import os, stat
for dp, dns, fns in os.walk(".venv"):
    for n in dns + fns:
        p = os.path.join(dp, n)
        m = os.stat(p).st_mode
        if not (m & stat.S_IWRITE):
            os.chmod(p, m | stat.S_IWRITE)