Usage — Local use
These are the steps for running ClimCanvas on your own PC and operating it in a browser on the same PC. If you have not installed it yet, see Install; for running it on a lab server or similar, see Remote use; for temporary use where several people connect to one PC, see Classes and demos.
Local mode
1. Launching the app
Activate the Python environment with the dependencies installed (Install 1.3), then run streamlit run in the ClimCanvas directory.
When it starts, a browser opens automatically. If it does not, open the URL shown in the terminal (usually http://localhost:8501) yourself. To quit, press Ctrl+C in the terminal.
On the first launch, a Streamlit card titled "Help agents write better apps" may appear at the top right of the screen. It is not a ClimCanvas feature; you can dismiss it with "Don't show again" (FAQ).
To launch on a different port (e.g. 8080), run with the following option in the terminal.
For how to load netCDF files after launch (specifying a path, "Browse...", "Choose from allowed directories", data whose longitude and latitude are in separate files), see Usage "2. Loading files".
2. Saving and restoring your work in progress (sessions)
A session file bundles the whole on-screen setup — the paths of the loaded netCDF files, the panel layout, the plot settings and so on — into a single JSON file. Use it to pause your work and resume later, or to remake the same figure.
There are two ways to save, but in local use the app and the browser are on the same machine, so both save to your own PC. The only differences are where the file goes and how much effort restoring takes. Both restoring ("Restore session") and saving ("Save" → "Session") are split into a pair of tabs, "this PC (blue) / upload / download (orange)", and the origin of the session being edited can be checked at any time in the banner of the same color above the figure.
Method A: save under a name on this PC
- Save: from the "Save" → "Session" → "To this PC" tab.
- Restore: from the "From this PC" tab in "Data & session loading" → "Restore session".
How saving and restoring behave depends on whether session_dirs is set in the configuration file (details of the configuration file).
- Without
session_dirs(default): the destination is fixed to the single location~/.climcanvas/sessions/(the folder is created automatically on the first save). "Destination directory" has only one choice, and the restore side shows no directory selection at all. - With
session_dirs: several candidate destinations can be registered, and the directory can be switched both when saving and when restoring (a "Directory" selection also appears on the restore side). Handy when you want to keep sessions in separate places per project.
Method B: upload / download
- Save: with the "Save session" button in the "Save" → "Session" → "Download" tab. The destination follows the browser's download settings. The file name is up to you — give it a name when saving or rename it afterwards (a file of any name can be restored).
- Restore: upload that JSON from the "Upload" tab in "Data & session loading" → "Restore session". After loading, the uploader switches to a "Loaded" display; to replace it, press "Load a different session file" and upload again.
Notes on restoring
- The session JSON contains only the paths of the netCDF files, not the data itself. Moving or deleting the original files makes the restore fail.
- The "Session file" field is for sessions only. It does not accept a personal preset JSON (place a preset at
~/.climcanvas/preset.jsonand it is applied automatically at startup).