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\Programing\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\Programing\Python\MICrONS data"
.\.venv\Scripts\Activate.ps1

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

(microns-data) PS C:\Users\lunel\Projects\Programing\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\Programing\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\Programing\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\Programing\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/ に書き出される。

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. テスト実行

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

uv run python -m unittest verify_refactor -v

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

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