Usage
This page explains how to launch the app, load netCDF files, save and restore sessions (your work in progress), and write the configuration file (config.toml). The basic workflow for making a figure (load → set the plot mode and layers → save) is in Basics in the manual.
1. Launching the app
ClimCanvas is an app written in Python; its user interface is built with Streamlit, a web UI framework (installed together with the other dependencies). "Launching" ClimCanvas therefore means running streamlit run app.py in a terminal, which starts a small web server dedicated to ClimCanvas on that machine. The interface opens in a browser (usually http://localhost:8501), but you are not visiting a site on the internet — you are simply connecting to the ClimCanvas running on that machine. Reading netCDF files and drawing figures both happen on the machine running the app; your data never leaves it.
The combination of "the machine running the app" and "the machine showing the browser" is what we call the deployment. The steps differ by deployment, so see the page that applies to you (if you have not installed ClimCanvas yet, go to Install first).
- Local use — launch on your own PC and use it in a browser on the same PC (the basic form for personal use)
- Remote use (SSH tunnel) — launch on a lab server or similar and use it from a browser on your own PC through an SSH tunnel
- Classes and demos — launch on one PC and let several people connect from their own browsers
2. Loading files
After launch, load a netCDF file from "New work" under "Data & session loading" in the sidebar. Once a file is loaded, you can load additional files from "Add a file". How you specify files depends on whether allowed_dirs is set in the configuration file (details of the configuration file).
- Without
allowed_dirs(default): netCDF files anywhere can be opened. Type the path into the "Path to netCDF file" field and press "Add", or pick the file in the OS file dialog via the "Browse..." button. - With
allowed_dirs: only files under the allowed directories can be opened (paths outside them give an error), and the "Browse..." button is not shown. Instead, "Choose from allowed directories" appears, where you can walk through folders and pick a netCDF file (the current location is shown as "allowed directory name/relative path"). Typing a path directly still works, but it is limited to the allowed directories. This feature is meant for remote connections to a server shared by several people, but it can also be used in local use.
Data whose longitude and latitude are in separate files (regional-model output where longitude and latitude are 2-D variables in separate files such as FLON.nc / FLAT.nc): open "Coordinate file (optional)" under each file in "Loaded files", specify the longitude file and the latitude file (only the longitude side if they are the same file), and press "Apply". The longitude and latitude are then attached as coordinates, and horizontal maps can be drawn. The setting is saved in the session, and the reproduction script opens the same files.
3. Saving and restoring your work in progress (sessions)
A session (work-in-progress) file bundles the whole figure setup — the paths of the loaded netCDF files, the panel layout, the plot settings and so on — into a single JSON file. There are two ways each to restore and to save a session file, switched with a pair of blue and orange tabs. Blue is the machine running the app (the tabs are named "From this PC / To this PC" in local use, or "From the server / To the server" when mode = "remote" is set); orange is file transfer to and from your own PC ("Upload / Download"). The origin of the session being edited is always shown in a banner of the same color above the figure.
Local use (launched on your own PC)
Since the app and the browser are on the same machine, both methods save to your own PC. The only differences are where the file goes and how much effort restoring takes (local use).
Remote use (launched on a lab server or similar)
Named saves "To the server" stay on the server. Even after closing the browser and coming back the next day, you can resume in one step from the list of file names as long as you connect to the same server. Download saves land on your own PC, so use them when you want to keep a local copy or take the JSON to another server or environment (remote use).
Notes on restoring
- The session JSON contains only the paths of the netCDF files, not the data itself. On restore, the files are reopened from the same paths, so moving or deleting the original netCDF files makes the restore fail.
- To restore on another machine, the netCDF files must be at the same paths on that machine.
- In an environment with
allowed_dirsset, paths are validated on restore as well. A session containing paths outside the allowed directories gives an error. - The UI language is not part of the session (it is saved in the startup preset instead). Loading a session does not change the display language.
For the steps in each deployment (choosing where to save and how to restore), see the following pages.
- Local use — both methods save to your own PC
- Remote use (SSH tunnel) — save under a name on the server, or download to your own PC
- Classes and demos — have participants use download saves
4. Where settings and state are stored — ~/.climcanvas/
ClimCanvas stores per-user settings and state in ~/.climcanvas/ in the home directory. "Home" here means the home on the machine running ClimCanvas: your own PC if you launched it there, or the server-side user's home if you launched it on a lab server. Note that it is not the machine showing the browser. You need to create this directory yourself.
| Path | Contents |
|---|---|
| config.toml | Configuration file (explained in section 5) |
| sessions/ | Default destination when saving a session under a name (blue tab "To this PC / To the server") |
| preset.json | Startup preset. Created with "Save preset" in the UI; preferences such as the UI language and fonts are then applied automatically at the next launch |
| cmaps/ | Custom colormaps. RGB text files placed here are loaded at startup and appear in the colormap choices as the "Custom" group (samples in 3 formats are in data/sample/cmaps/ of the distribution) |
5. Configuration file — ~/.climcanvas/config.toml
The app works without it (everything at default values). With it, you can change the following three things. A template is in config.example.toml at the repository root; copy it, rename it and use it as ~/.climcanvas/config.toml. The format is TOML, and ~ in paths is expanded.
The settings are read when the app starts or reloads; after editing the file, reload the browser.
| Key | Meaning |
|---|---|
| allowed_dirs | Allow-list of directories from which netCDF files can be opened. No restriction if unset (the default for local use). When set, paths outside the listed directories give an error, and the "Browse..." button (file dialog) disappears so that only path entry remains. Set it for remote use. You can also set it in local use if you want the folder browser "Choose from allowed directories" |
| session_dirs | Candidate destinations for saving a session under a name. They become the choices of "Destination directory" in the UI. If unset, ~/.climcanvas/sessions is the only one |
| mode | Set to "remote" for the remote-use display (the blue session tabs become "From the server / To the server", and the banner reads "session … saved on the server"). Always treated as local if unset ("From this PC / To this PC") — it is not inferred from the connecting host |
Overriding with environment variables
The same settings can be passed as environment variables (:-separated). If an environment variable is set (even to an empty value), it takes precedence over config.toml. This is handy for changing the restriction temporarily: CC_ALLOWED_DIRS="" launches the app with the restriction in config.toml lifted.