使い方
このページでは、アプリの起動方法から netCDF ファイルの読み込み、セッション (進行中の作業状態) の保存・復元、設定ファイル (config.toml) の書き方を説明します。図を作る基本の流れ (読み込み → 描画モードとレイヤーの設定 → 保存) はマニュアルの基本操作にあります。
1. アプリの起動方法
ClimCanvas は Python で書かれたアプリで、操作画面の表示に Streamlit という Web UI フレームワークを使っています (インストール時に依存パッケージとして一緒に入ります)。そのため ClimCanvas を「起動する」とは、ターミナルで streamlit run app.py を実行して、そのマシンの中に ClimCanvas 専用の小さな Web サーバーを立てることを指します。操作画面はブラウザで開きますが (通常 http://localhost:8501)、インターネット上のサイトを見ているのではなく、そのマシンで動いている ClimCanvas に繋いでいるだけです。netCDF の読み込みも図の描画もアプリを動かしているマシン側で行われ、データが外に出ることはありません。
この「アプリを動かすマシン」と「ブラウザで見るマシン」の組み合わせが運用形態です。手順は運用形態によって違うので、当てはまるページを参照してください (本体の導入がまだなら、先にインストールのページへ)。
- ローカル運用の場合 — 手元の PC で起動し、同じ PC のブラウザで使う (個人利用の基本形)
- リモート運用の場合 — 研究室サーバー等で起動し、SSH トンネル経由で手元 PC のブラウザから使う
- 演習・デモ運用の場合 — 1 台の PC で起動し、複数人がそれぞれのブラウザから接続する
2. ファイルの読み込み
起動後は、サイドバーの「データ・セッション読み込み」の「新規作業」から netCDF ファイルを読み込みます。ファイル読み込み後は「ファイルの追加」から複数のファイルを読み込むことができます。指定方法は、設定ファイルの allowed_dirs (設定ファイルの詳細) の有無で変わります。
allowed_dirsの指定が無い場合 (デフォルト): どの場所の netCDF でも開けます。「netCDFファイルのパス」欄にパスを直接入力して「追加」を押すか、「参照...」ボタンで OS のファイル選択ダイアログから選びます。allowed_dirsを指定した場合: 開けるのは許可ディレクトリ配下のファイルだけになり (配下以外のパスはエラー)、「参照...」ボタンは表示されません。代わりに「許可ディレクトリから選ぶ」が現れ、フォルダを辿って netCDF ファイルを選べます (現在地は「許可ディレクトリ名/相対パス」で表示されます)。パスの直接入力も引き続き使えますが、許可ディレクトリ配下に限られます。複数人で使うサーバーにリモート接続する時に用いる機能ですが、ローカル運用時も使えます。
経緯度が別ファイルにあるデータ (領域モデルの出力で、経度・緯度が FLON.nc / FLAT.nc のような別ファイルの 2 次元変数になっているもの) は、「読み込み済みファイル」の各ファイルの下にある「座標ファイル (任意)」を開き、経度のファイルと緯度のファイル (同じファイルなら経度側だけ) を指定して「適用」を押すと、その経緯度が座標として結び付き、水平断面図が描けるようになります。指定はセッションに保存され、再現スクリプトも同じファイルを開きます。
3. 進行中の作業 (セッション) の保存と復元
セッション (進行中の作業状態) ファイルとは、読み込んだ netCDF のパス・パネル構成・描画設定など、図の設定一式を 1つの JSON ファイルにしたものです。セッションファイルの復元/保存の方式はそれぞれ2系統あり、青とオレンジの対のタブで切り替えます。青はアプリを動かしているマシン側 (タブ名はローカル運用の場合「PC から/PCへ」、mode = "remote" 設定時は「サーバーから/サーバーへ」)、オレンジは手元 PC とのファイル受け渡し (「アップロード/ダウンロード」) を表します。編集中のセッションの由来は、図の上に同じ色のバナーで常時表示されます。
ローカル運用の場合 (手元の PC で起動)
アプリとブラウザが同じマシンなので、どちらの方式でも保存先は自分の PC です。違いは置き場所と復元の手間だけ（ローカル運用の場合）。
リモート運用の場合 (研究室サーバー等で起動)
「サーバーへ」の名前付き保存はサーバー側に残ります。翌日ブラウザを開き直しても、同じサーバーに接続すればファイル名の一覧から一発で再開できます。一方ダウンロード保存は手元 PC に落ちるので、手元に控えを残したいときや、JSON を別のサーバー・別の環境へ持っていきたいときに使います（リモート運用の場合）。
復元時の注意
- セッションの JSON に入っているのは netCDF のパスだけで、データ本体は含まれません。復元時に同じパスからファイルを開き直すため、元の netCDF を移動・削除すると復元に失敗します。
- 別のマシンで復元するには、そのマシンの同じパスに netCDF が置かれている必要があります。
allowed_dirsを設定した環境では、復元時にもパスの検証が行われます。許可ディレクトリ外のパスを含むセッションはエラーになります。- UI 言語はセッションに含まれません (起動時プリセット側で保存されます)。セッションを読み込んでも表示言語は変わりません。
運用形態ごとの手順 (保存先の選び方と復元の操作) は次のページを参照してください。
- ローカル運用の場合 — どちらの方式でも保存先は自分の PC
- リモート運用の場合 — サーバー内に名前を付けて保存するか、手元 PC にダウンロードするか
- 演習・デモ運用の場合 — 参加者にはダウンロード保存を使わせる
4. 設定・状態が保存される場所 — ~/.climcanvas/
ClimCanvas はユーザーごとの設定と状態をホームディレクトリの ~/.climcanvas/ に保存します。ここでの「ホーム」は ClimCanvas を動かしているマシンのホームです。手元の PC で起動していれば手元の PC、研究室サーバーで起動していればサーバー側ユーザーのホームになります。ブラウザで見ているマシンではない点に注意してください。このディレクトリは自身で作成してもらう必要があります。
| パス | 中身 |
|---|---|
| config.toml | 設定ファイル (5 節で解説) |
| sessions/ | セッションを名前を付けて保存する (青タブ「PC へ / サーバーへ」) ときの既定の保存先 |
| preset.json | 起動時プリセット。UI の「プリセットの保存」で作られ、次回起動時に UI 言語やフォントなどの好み設定が自動適用される |
| cmaps/ | カスタムカラーマップ。RGB のテキストファイルを置くと起動時に読み込まれ、カラーマップ選択肢に「Custom」グループとして現れる (配布物の data/sample/cmaps/ に 3 形式のサンプルあり) |
5. 設定ファイル — ~/.climcanvas/config.toml
無くても動きます (すべて既定値で動作)。置くと次の 3 つを変えられます。雛形はリポジトリ直下の config.example.toml にあるので、コピーしファイル名を変更して使ってください（~/.climcanvas/config.toml ）。書式は TOML で、パスの ~ は展開されます。
設定はアプリの起動・再読み込み時に読まれます。書き換えたらブラウザをリロードしてください。
| キー | 意味 |
|---|---|
| allowed_dirs | netCDF を開けるディレクトリの許可リスト。未設定なら制限なし (ローカル運用の既定)。設定すると、指定ディレクトリ配下以外のパスはエラーになり、「参照...」ボタン (ファイル選択ダイアログ) も出なくなってパス入力のみになります。リモート運用で使う場合に設定してください。ローカル運用でも、フォルダを辿れる「許可ディレクトリから選ぶ」ブラウザを使いたい場合に設定できます |
| session_dirs | セッションを名前を付けて保存するときの保存先候補。UI の「保存先ディレクトリ」の選択肢になります。未設定なら ~/.climcanvas/sessions の1つだけ |
| mode | "remote" にするとリモート運用向けの表示になります (セッションの青タブが「サーバーから/へ」、バナーが「サーバー内のセッション」)。未設定なら常にローカル扱い (「PC から/へ」) — 接続元からの自動推定はしません |
環境変数での上書き
同じ設定は環境変数でも渡せます (: 区切り)。環境変数が設定されていれば (空でも) config.toml より優先されます。一時的に制限を変えたいときに便利で、CC_ALLOWED_DIRS="" とすれば config.toml の制限を一時的に解除して起動できます。